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Introduction 

Over the years the original MDL (pronounced "Muddle") Primer by Greg Pfister [Pfister 72] became 
more and more a reference manual and less a Primer from which a novice could learn the language 
Some of the text of the original has been re-used in this document, but much has been eliminated 
changed, or re-ordered, and a reasonable amount of new material has been added. In particular a 
number of figures and many more examples have been added to make some of the more difficult 
concepts easier to understand. 

This Primer is intended as an introduction to MDL. After assimilating the information contained 
herein, you should be able to write very good programs. However, for any individual topic in the MDL 
Pnmer there is likely to be more information available in The MDL Programming Language [Galley 79] 
and The MDL Programming Environment [Lebling 80], and there are many topics in these documents 
which are not addressed in the Primer. Anyone who plans to do any serious work with MDL should 
read these documents. 

One of the difficulties in writing a Primer is to make it useful to those who don't know anything at all 
about programm.ng without boring those who know a lot of the basics. Hopefully those at both 
extremes will find this to be easy to read. If you are a complete novice, however, there may be some 
unfamiliar references and some material which doesn't make sense on your first reading. 

Why MDL? 

Many people ask this. It is often hard for those who use MDL to put into words their reasons for 
liking it. Those of us who use MDL are convinced that it is a better language than any other we've 
encountered. Unfortunately, very little has been done to convince others of this and spread the use of 
this marvelous tool. 

MDL was created in the early 1970's by a group at the Dynamic Modelling/Computer Graphics 
d.v.s.on of MIT's Project MAC (later renamed the Laboratory for Computer Science). It is an offshoot 
of the original Lisp. There have been quite a few offshoots of Lisp in the past 10 years - MacLisp 
InterUsp, Lisp Machine Lisp, Lisp1.5, UCI Lisp, Franz Lisp, etc., etc. - but none of them are like MDL. 

Since MDL is a distant relative of Lisp and many of those first learning MDL have some familiarity 
with Lisp, a short comparison of the two languages follows. If you are not familiar with Lisp (or, better 
still, with any. other languages) count your blessings (you don't have any bad habits to unlearn) and 
skip the following discussion. 

MDL's similarities to Lisp: MDL shares the advantages of Lisp over the more popular languages 
such as Basic, Fortran. Cobol, Algol, Pascal, etc. 

- It has an interpreter which allows real-time interaction and allows you to define and test 
individual functions separately. 
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- Its syntax is very simple. 

- Any data object or function can be passed as an argument or returned as a value. 

- It has list structures equivalent to Lisp's. 

- Recursive functions can be written quite easily. 

The similarities between MDL and Lisp are such that in many cases a few minor changes to Lisp 
code will convert it into working MDL code. Given the other features of MDL, no MDL programmer 
would write the program in the same Lisp style. 

MDL's dissimilarities to Lisp: Many objections to Lisp are answered in MDL. 

• Strongly typed languages provide much better error detection tools than Lisp. MDL 
allows declarations of all variable types to whatever level of complexity is desired. A 
variable can be declared to be one of several types. 

- Recursion is a useful tool, but often is not a very efficient way to solve the problem. Lisp's 
motto "To iterate is human, to recurse divine," is not one of MDL's tenets. MDL allows 
recursion, but provides excellent facilities for iteration. 

- MDL has a very powerful set of data structures - Lists, Strings, Vectors, and Uniform 
Vectors. Although lists are a very useful and flexible form of structure, they are certainly 
not optimal in all cases. MDL's various structures allow the user to save space and 
access time. MDL's structures are also "first class," in that the standard functions for 
manipulating data structures can be used on all of them equivalent^. 

- Probably the biggest complaint against Lisp-like languages is that they are unsuitable for 
"production programming" because they are too slow. MDL has an excellent compiler 
which as far as we know is the best compiler for a Lisp-like language. It produces 
machine code equivalent in efficiency to Fortran and Cobol. which are considered very 
efficient. 

• MDL has a rich library of useful program aids. The editing and debugging functions are 
among the best. The package system allows building of very large programs from small 
sections, usually written by different people, without worrying about variable name 
conflicts. 

• Probably the most distinctive feature of MDL is its mechanism for user-defined types. 

which is the best of any language with which we are familiar. User-defined types have 

been retrofitted on some of the newer versions of Lisp, but in most cases they can be 

used only with special functions and cannot be used in the same general way that Lists 
can. 

Hopefully some of your questions have been answered and you have some ready answers when 
you get flak from your non-MDL programming friends. Learning MDL should be an enjoyable and 
worthwhile experience. Your reactions to this Primer and suggestions for changes are always 
welcome. Good luck! 
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Warning! You are about to embark on an undertaking fraught with peril. MDL programming has 
been proven to be habit-forming. Once you begin, you may find the habit hard to kick! 
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1. Basic Interaction 



The purpose of this chapter is to provide you with that minimal amount of information needed to 
experiment with MDL (pronounced, affectionately, as Muddle) while reading this document. It is 
strongly recommended that you do experiment, especially upon reaching chapter 6 (page 27) (Simple 
Functions). 



1.1. Loading MDL 

First, catch your rabbit. Somehow get the interpreter running -- the program in the file SYS:TS 
MDL in the ITS version or SYS : MDL . SAV in the Tenex version or SYS : MDL . EXE in the Tops-20 version. 
[Just type :MDL to ITS, MDL or MUDDLE to Tops-20.] The interpreter will then type 

MUDDLE nnn IN OPERATION. 
LISTENING-AT-LEVEL 1 PROCESS 1 

and then wait for you to type something. 

The program which you are now running is an interpreter for the language MDL. Al] it knows how 
to do is interpret MDL expressions. There is no special "command language"; you communicate with 
the program -- make it do things for you -■ by actually typing legal MDL expressions, which it then 
interprets. Everything you can do at a terminal can be done in a program, and vice versa, in exactly 
the same way. 

The program will be referred to as just "MDL" (or "the interpreter") from here on. 



1.2. Typing 

Typing a character at MDL normally just causes that character to be echoed (printed on your 
terminal) and remembered in a buffer. The only characters for which this is normally not true act as 
follows: 

Typing the "Escape" or "Alt-Mode" key, which we will always refer to as S (dollar-sign), causes 
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K Q DL J ech ° dollar - si 9 n and "uses the contents of the buffer (the characters which you've typed) to 

=nn unT r f ™.f expression ' s > in M DL. When this interpretation is done, the result will be printed 
and MDL will wait for more typing. 

JOSS. ""I 6 "."I "' ° haraC,er (DEL '" the ITS and Tops2 ° «*«* conlral " A in «• Tenex version) 

I7J f ^ "other rubout. once again the las. character is deleted -namely/the 

second most receny typed. Etc. The character deleted is echoed, so you can see what you're 

d,™? 7„Th ? y ,erm,na ' S ' rUb ° U! Wi " " eCh0 " by causi "9 "" deleted character o 
disappear. If no characters are In the buffer, rubout echoes as carriage- return line-feed. 

returnl 9 e?e e d° n,r0l ' a,Si9n) de ' e ' eS eWm ^ haW **" SinCe ' he lasl *' and Drinls a carria 9<" 

to ^eTh^.Tn'' ? ?3USe ! ' he CUrre "' inpUt bu " er ,0 ta ^P" 1 back ° u < at vou. This allows you 
to see what you really have, without the confusing re-echoed characters produced by rubout. 

■ d S l l J°",T L) P T C f, S r ' he Same e,,eC * M ^P 1 " 9 tD ' exce P' <"*■ ■ vour terminal is a 
reS ( P 6 ' VT10 °' VT62, H19 ' "* ,he Screen is cleared before the input buffer is 

J£?££££PJE2 MD \, '° S, ° P Wha ' eVer " b d0i " 9 and act " if " e "° r had oocurred 
of a como^iS V '^""'t I I" " USe ' Ul ,0r ,emporar V interruptions to check the progress 
of a computation. tG ,s "reversible" - that is, it does not destroy any of the "state" of the 

computahon rt interrupts. To "undo" a tG, type the characters 
<ERRET T>$ 

(This is discussed more fully far below, In chapter 14, page 1 15 (Debugging MDL Programs).) 

■WwlfS^S "It" t° tMm *"* Wha ' " iS CUrre " ,,y d0in9 «« relurn <° a "om»l 
hbtening state. ( n the Tenex and Tops-20 versions, tO also should have the same effect ) tS is 

2X5 StigZSr* loops - similar *-* "*» * s ^ SJ s 



nested I vn,!?nH k " 1C ' Ude braCkB ' S " «3 eneri = a »y mean.) that must be correctly paired and 

ult f h V u 1 " r ^P" 19 W " h ,ne pair °' chara o'ers 1$ (exclama.ion-poin. ESC) all currentlv 
S and intrf £2 n0,d ° Uble « uoles ' " hi ' h bracket strings of characters) will alma, caly be 
M n?f h « I , f^ Wi,h ° U ' ' he ' ' MDL Wi " iusl sit lhere wai > in 9 'or you to pair t em 

iz^ e ^^^s:z^:c^ e,c - wi,hin ,he expression - iyped an - 

J^JS'^SS'SSTS, Paifed and $ (ESC) iS «» ed - MDL wi " immediately echo carriage- 

no. o ec ^d vou t lL h r eXl "" ng " Prin,S Wi " bS ,he reSU " 0l ,he "**•*• S« if a plnin $ is 
so echoed, you have some expression unclosed. In ,ha. case, if you have no. typed any 
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characters beyond the $, you can usually rub out the $ and other characters back to the beginning of 
the unclosed expression. Otherwise, what you have typed is beyond the help of rubout and t@; if you 
want to abort it, use tS. 

MDL accepts and distinguishes between upper and lower case. All "built-in functions" must be 
referenced in upper case. 



1.3. Errors ■■ Simple Considerations 

When MDL decides for some reason that something is wrong, the standard sequence of evaluation 
is interrupted and an error function is called. This produces the following terminal output: 

•ERROR* 

often-hyphenated-reason 
function-in-which-error-occurred 
LISTENING-AT-LEVEL integer PROCESS integer 

You can now interact with MDL as usual, typing expressions and having them evaluated. There 
exist facilities (built-in functions) allowing you to find out what went wrong, restart, or abandon 
whatever was going on. In particular, you can recover from an error -- that is, undo everything but 
side effects and return to the initial typing phase - by typing the following first line, to which MDL will 
respond with the second line: 

<ERRET>$ 

LISTENING-AT-LEVEL 1 PROCESS 1 

If you type the following line while still in the error state (before <ERRET>), MDL will print the 
FRAMES it went through to evaluate the function: 

<FRAMES>$ 

Typing FR& (pronounced 'frampersand') instead of FRAMES will cause MDL to print a condensed, 
usually more readable output. 

This will also be explained in chapter 14. 
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2. MDL Basics 



In a general sense, when you are interacting with MDL, you are dealing with a world inhabited only 
by a particular set of things: MDL objects. 



2.1. Introduction to MDL TYPES 

MDL objects are best considered as abstract entities with abstract properties. The properties of a 
particular MDL object depend upon the class of MDL objects to which it belongs. This class is known 
as the TYPE of the object, and every MDL object has one. Easily recognized TYPES include 
FIX (integers) and FLOAT (real numbers). Examples of these might be 1 and 2.67, respectively. An 
abbreviation often used is to refer to "a FIX" when referring to a MDL object whose TYPE is FIX. For 
example, 1 is a FIX and 2.67 is a FLOAT. 

MDL TYPEs can be divided into two general classes: those with internal structure and those without 
internal structure. The former will be referred to as being structured. Structured objects are those 
which can be thought of as an ordered series of items held together in some way. There are a number 
of ways in which these items can be held together, and each of these is represented by a series of 
MDL objects between a set of matched brackets (e.g. <>.().[].{} "")- As will be seen later, each 
bracket type represents a different TYPE of MDL object, and some represent different ways of 
Internally storing the series of objects. Depending on the application, one of these may be more 
suitable than another. 

Here are some MDL objects which are not structured: 

20 

20.0 

TWENTY 

The first two are examples of TYPEs FIX and FLOAT, as noted above. The last is an ATOM, roughly 
speaking an identifier or a variable, and will be discussed in Chapter 3. 

Here are some MDL objects which are structured: 
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<+ 1 2> 

(+ 1 2) 

C+ 1 2] 
»+ 1 2 B 



These represent very similar notions: an ordered series of the MDL objects +. 1, and 2, the first of 
these being an ATOM and the rest FIXes. These brackets correspond to the TYPEs FORM, LIST and 
VECTOR. The first of these, a FORM, is central to MDL. as it represents the application of a function to 
arguments. The others will be considered later. 



2.2. Printing of MDLObjects 

We have already seen the printed representation of some MDL objects: FIXes, FLOATs, FORMs 
LISTs and VECTORS. As will be mentioned later, MDL allows an almost unlimited number of data 
types Obv.ously, there are not enough bracket types to make each data type recognizable. 
Therefore, most MDL types have a kind of generalized way of printing. This format is like this: 

fftype-name value 

where type-name is the name of a MDL TYPE and value describes the 'value' of the object. Suffice it 
for now to say that an object which prints like: 

#FALSE () 

is of TYPE FALSE and an object which prints like 

#MUMBLE [1 2 3] 
is of TYPE MUMBLE. 



2.3. MDL FORMS 

A FORM in MDL is printed as: an open angle bracket (<), the name of the function to be applied the 
arguments to wh.ch the /unction is being applied, and finally a closing angle bracket (>). MDL's angle 
brackets are one of its distinguishing features (almost as distinctive as Lisp's parentheses). 

MDL has a large number of built-in functions. These are usually of TYPE SUBR (short for 
subroutine). For example: 



MDL BASICS 
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<+ 1 2 3> 

will, when given to the MDL interpreter, return 6. The way in which the name for a function, in this 
case +, is associated with its functional part (i.e. in this case, the thing which actually performs the 
addition) is described later. Suffice it for now to say that these functions can be referenced by their 
name (an ATOM), as was done in the example. 



2.4. Prefix Notation 

MDL is a distant relative, a much-improved descendant of LISP. The "desirable features" of LISP 
were included in MDL. One of those features, prefix notation, you have just seen. 

Prefix notation, sometimes referred to as Polish notation, is different from the infix notation of 
ordinary arithmetic and reverse-Polish notation of some calculators. Below are some examples of 
equivalents in infix and prefix notation: 

4 + 7 
<+ 4 7> 

8 - 6 

<- 8 6> 

- 

8 - (3 + 2) 
<- 8 <+ 3 2» 

- 

9+ (4 •6-8/3) 

<+ 9 <- <• 4 6> </ 6 3>» 

7 + 3 + 4 + 8+11 
<+ 7 3 4 8 11> 

It will take you some time to become accustomed to prefix notation. One thing you will have to 
keep in mind is balancing of brackets. Notice that with prefix notation an operator can take an 
arbitrary number of arguments and that the nesting is never ambiguous (i.e. the parentheses of infix 
notation are not necessary). 



2.5. Evaluation of FORMS 

Evaluation of a MDL FORM proceeds from left to right. The first item is the name of the function 
which will be applied to Ihe arguments which follow. The arguments may themselves lie FORMs which 
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will be evaluated in the same way. For example, this FORM: 
<+ <+ 1 2> 3> 



ss2:s:;r* * ,he "•* — <*•**■ — « 

second argument. The argument ma b ?j£, 1 * * ^ UB) 3 " d ,hen ,0 ,he evalua,ion °< «« 

evaluation before a result is™ neT , b tEZZSZ ^'l* ^ " hiS and re * uke man * "**<* °' 

evaluation has a resu.ting vaiue^ev^l see even » T '^ Un " ke m8ny ° ,her ' angua9es ' ever * 
of variables return values ' '" SUCh °P era "°"S as printing or setting the values 



2.6. Introduction to Truth 

C^^^^^^Z^^.^ —on sideredtrue. „ an 
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3, Read, Evaluate, and Print 



3.1. General 

Once you type $ and all brackets are correctly paired and nested, the current contents of the input 
buffer go through processing by three functions successively: first READ, which passes its output to 
EVAL ("evaluate"), which passes its output to PRINT, which types its output on the terminal. 

Functionally, 

READ: printed representations ■-> MDL objects 

EVAL: MDL objects •> MDL objects 

PRINT: MDL objects --> printed representations 

That is, READ takes ASCII text, such as is typed in at a terminal, and creates the MDL objects 
represented by that text. PRINT takes MDL objects, creates ASCII text representations of them, and 
types them out. EVAL. which is the really important one, performs transformations on MDL objects. 



3.2. EVAL and TYPEs 

The laws of the MDL world are defined by EVAL. In a very real sense, EVAL is the only MDL object 
which "acts", which "does something". In "acting", EVAL is always "following the directions" of 
some MDL object. Every MDL object should be looked upon as supplying a set of directions to EVAL; 
what these directions are depends heavily on the TYPE of the MDL object. 

Since EVAL is so ever-present, an abbreviation is in order: "evaluates to something" or "EVALs to 
something" should be taken as an abbreviation for "when given to EVAL, causes EVAL to return 
something". 
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3.3. Example (TYPE FIX) 

IS 
i 

The following has occurred: 

-^^^WiiKittriaKSfi sis type fix ' in 

poini is understood always to be in a Led nosit on », ,h„ ■ m h * f ff 8 "' be ° aUSe ,he decimal 
corresponding ,o the decimal reprei^nCd SEES? "* "" *" "" ^ ■*" 

M*SlSiX5a^ -1m " X - *-*««"« devaluates toi.se, so 

J5KS52S5Si!T FIX ' " nd prin,ed on ,he ,erminal ,he decimai <****< 

3.4. Example (TYPE FLOAT) 

1.0$ 
1.0 

TY^K^S^ an3l09C : US t0 ^ PreCeding examp,e ' «* «»t the MDL object was of 

3.5. FIXes and FLOATs versus READ: Specifics 
3.5.1. READ and FIXed-point Numbers 

JESS TSES&SESgZS. JS25 ? be l FIx r ,he radi * ° f ,he 

grouping represents a negative FIX ?he a roes. F )t 11 ' 1 m ' ' mmec " a,elv P recedin 9 such a 
power minus one, or 34 359 733 367 tteS I rep f Sen,able on ,he «M0 is two to the 35th 

number. VmJ^ESSESSmEEKSEE^^ *** *"" *" "^ °' ,ha ' 
you write attempts to produce a M : oulS* nh J lot 9 REA ° conve " s » «° a FLOAT; if a program 
errors are disabled) * ' "' ra " 9e ' a " 0ver " ow error *■ «*ur Meffl overflow 
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3.5.2. READ and PRINT versus FLOATing-point Numbers 

PRINT can produce, and READ can understand, two different formats for objects of TYPE FLOAT. 
The first is "decimal-point" notation, the second is "scientific" notation. Decimal radix is always used 
for representations of FLOATs. 

"Decimal-point" notation for a FLOAT consists of an arbitrarily long string of digits containing one . 
(period) which is followed by at least one digit. READ Will make a FLOAT out of any such object, with a 
in limit of precision of one part in 2 to the 27th power. (FIXed and FLOATing-point numbers are stored in 

al one 36-bit PDP-10 word. FLOATing-point numbers give up precision to gain their greater range.) 

ct 

"Scientific" notation consists of: 

yQ 1 . a number, the mantissa 

2. immediately followed by E or e (upper or lower case letter E), 

3. immediately followed by an exponent, 

where the mantissa is an arbitrarily long string of digits, with or without a decimal point (see following 
note); and the "exponent" is up to two digits worth of FIX. This notation represents the "number" to 
the "exponent" power of ten. Note: if the mantissa as above would by itself be a FIX, and if the 
"exponent" is positive, and if the result is within the allowed range of FIXes. then the result will be a 
FIX. For example, READ understands 10E1 as 100 (a FIX), but 10E-1 as 1. 0000000 (a FLOAT). 

The largest-magnitude FLOAT which can be handled without overflow is 1.7014118E+38 (decimal 
radix). The smallest-magnitude FLOAT which can be handled without underflow is . 14693879E-38. 



jr 



Examples: 



1.001$ 
1.001000 



.001$ 
1.0E-3 



143E2S 
14300 



1234567891234$ 
1.2345878E+12 
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4. Atoms and Their Values 



4.1 . Example (TYPE ATOM, PNAME) 

In the previous chapter, the handling of FIXed and Floating point numbers by READ, EVAL. and 
PRINT wasdiscussed. If you type: 

GEORGES 
GEORGE 

a lot more happens. 

READ noted that what was typed had no special meaning, and therefore assumed that it was the 
representation of an object of TYPE ATOM. ("Atom" means "more or less indivisible.") READ 
therefore attempted to look up the representation in a table it keeps for such purposes, if READ finds 
an ATOM in its table whose representation matches the representation just received, that ATOM is 
returned as READ'S value. If the look-up fails, READ creates a new ATOM, puts it in the table with the 
representation read, and returns the new ATOM. Nothing which could in any way be referenced as a 
legal "value" is attached to the new ATOM. The initially-typed representation of an ATOM becomes its 
PNAME, meaning its name for PRINT (£RINT NAME) . One often abbreviates "object of TYPE ATOM 
with PNAME name" by saying "ATOM name". There is a reason for making this careful distinction. 
Unlike other languages where atoms are names associated with values, a MDL ATOM is an object 
which mav have values (global and/or local) but which is distinct from its value(s). 

EVAL, given an ATOM, returned just that ATOM. 

PRINT, given an ATOM, typed out its PNAME. 



4.2. READ and PNAMEs 

The question "what is a legal PNAME?" is actually not a reasonable one to ask; any non-empty 
string of arbitrary characters can be the PNAME of an ATOM. However, some PNAMEs are easier to type 
to READ than others. But even the question "what are easily typed PNAMEs?" is not too reasonable, 
because: READ decides that a group of characters is a PNAME by def.Tul(; if it can't possibly be 
anything else, it's a PNAME. So, the rules governing the specification ol PNAMEs are mossy, and best 
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work If lor ,omp r il J " d < c "stomarily) hyphens to be a PNAME; that will always 

ZH££X£Sl Z^SSST de,ails *°" ,e9al PNAHES ' r Subsec,L 



4.3. Values of ATOMS 



4.3.1. General 



Jisssrjssff ssasREsa H ,o k ,he atom wim pnahe ge °» ge — 

structures. They are de«n7i „L, ! M ° L Sen " M war,abl8S and « "«"« tor functions and data 



structures. They are definitely useful. 

values are referred to a. me Si 1 L ri ! . 7 ""T" '" "° Way " These ,wo «««lonal 

reference the local and I bal^ef^an AT "« ±T m ^ £ V™ 1 ^ ,UnC "' 0nS WhiCh 
global values, follow. ' SOme of ,he characteristics of local versus 

4.3.2. SETG 

^A global value can be assigned to an ATOM by the SUBR SETG ("set global," pronounced •set-gee',, 
<SETG atom any> 

argument, namely the new global value of a'om. 9 * Va '" e nbmed by *" SETG is i,s ««* 



Examples: 



<SETG F00 <SETG BAR 489»$ 
469 



pom! 



££S J? "* **" ValUeS °' »* ,he ™ «» " «- "OH BAR epua, to the FlXed- 
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<SETG BAR FOO>$ 
FOO . 

That made the global value of the ATOM BAR equal to the ATOM FOO. 



4.3.3. GVAL 

The SUBR GVAL ("global value") is used to reference the global value of an ATOM. 
<GVAL atom> 



n 
ta 



o 

ii 
h 
s 



returns as a value the global value of atom. If atom does not evaluate to an ATOM, or if the ATOM to 
which it evaluates has no global value, an error occurs. 

GVAL applied to an ATOM anywhere, in any function, will return the same value. Any SETG 
anywhere changes the global value for everybody. Global values are context-independent. 

READ understands the character , (comma) as an abbreviation for an application of GVAL to 
whatever follows it. PRINT always translates an application of GVAL into the comma format. The 
following are absolutely equivalent: 



.aforn <GVAL afom> 

Assuming the examples in section 4.3.2 (page 20) were carried out in the order given, the following 
will evaluate as indicated: 



.FOOS 

469 

<GVAL FOOS 

469 

.BARS 

FOO 

..BARS 

469 



4.3.4. SET 

The SUOR SET is used to assign a local value to an ATOM. Applications of SET are of the form 
<SET atom any> 
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SET returns EVAL of any just as SETG does. 

Examples: 



<SET BAR <SET F00 100»$ 
100 



an 



Both BAR and F00 have been given (oca. values equal to the FIXed-point number 100. 

<SET F00 BAR>$ 
BAR 

F0O has been given the local value BAR. 



4.3.5. LVAL 

lowing two mJSS^^^S^SXwS^t^ "^ Pr0dUC6S ft Th ° 
Object, it returns the current local vaTue TatomT P "* °" *• corres P°"<*"3 MDL 

<LVAL afom> . a / om 

.BARS 
100 

<LVAL BAR>$ 

100 

.F00$ 
BAR 

,.F00$ 
F00 

...F00S 
489 
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5. Built-in Functions 



5.1 . Evaluation of FORMs 

EVAL applied to a FORM acts as if following these directions: 

First, examine the tunc (first member) of the FORM. If it is an ATOM, look at its GVAL. If it is not an 
ATOM, EVAL it and look at the result of the evaluation. If what you are looking at is not something 
which can be applied to arguments, complain (via the ERROR function). Otherwise, inspect what you 
are looking at and follow its directions in evaluating or not evaluating the arguments and then "apply 
the function" -• that is, EVAL the body of the object gotten from tunc. 



5.2. Built-in Functions (TYPE SUBR, TYPE FSUBR) 

The built-in functions of MDL come in two varieties: those which have all their arguments EVALed 
before operating on them (TYPE SUBR, for "subroutine", pronounced 'subber') and those which have 
none of their arguments EVALed (TYPE FSUBR, historically from Lisp [Weinreb 78], pronounced 
'effsubber,' for 'funny-SUBR'). Collectively they will be called F/SUBRs, although that term is not 
meaningful to the interpreter. See Appendix 2, Predefined Subroutines, in The MDL Programming 
Language [Galley 79] manual for a listing of all F/SUBRs and short descriptions. The term 
"Subroutine" will be used herein to mean both F/SUBRs and compiled user functions. 

Unless otherwise stated, every MDL built-in Subroutine mentioned is of TYPE SJJBR. Also, when it 
is stated that an argument of a SUBR must be of a particular TYPE, note that this means that EVAL of 
the argument must be of the particular TYPE. 

Another convenient abbreviation which will be used is "the SUBR pname" in place of "the SUBR 
v/hich is initially the GVAL of the ATOM of PNAME pname". "The FSUBR pname" will be used with a 
similar meaning. These distinctions are necessary. The SUBR is actually the global value of the ATOM 
of PNAME pname. The important point is that the ATOM effectively points at the " real function." For 
instance, 

<GVAL SET>$ 

#SU0R *000000746616* 
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rJ^.TniT S °, i " Cli " ed ' you could chan 9 e «»»• ATOM which points to a given FUNCTION or have 

bZZtZSS- I," "Z FUNCTI ° N ' A " bU '"- in SUBRS and FSUBRs *»» •» referred .on.** 
ahnnHhi,! 1 Wh h IC 1 h , P0, " ts, ° ,hem wl ™ MDL Starts up. The pom. is that there is nothing Jaced 
about these names, but for clarity's sake it is recommended that you no. rename them. 



5.3. Examples (+ and FIX; Arithmetic) 

<+ z 4 6>$ 
12 

HAl he MO U n B a.trS? ««£' °,'^ e US " a ' ari,hme ' iC ' UnCti0nS m MDL SUBRs: ♦■ - '• '. ««■ 

<fix i.o>$ i 

<+ 6 <• 2 3»$ 

11 

<SQRT <+ <• 3 3> <• 4 4>»$ 

6.0 

<- 6 3 2>$ 



<- 6>$ 

-6 

<MIH 1 2.0>$ 

1.0 

</ 11 7 2.0>$ 

0.6 

sataat'saiMsasissssssar*-*' 
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5.4. Arithmetic: Details 



+, -. •, /, HIN, and MAX all lake any .number of arguments, doing the operation with the first 
argument and the second, then with that result and the third argument, etc. If called with no 
arguments, each returns the identity for its operation (0, 0. i. 1. the greatest FLOAT, and the least 
FLOAT, respectively); if called with one argument, each acts as if the identity and the argument had 
been supplied. They all will cause an overflow or underflow error if any result, intermediate or final is 
too large or too small for the machine's capacity. Examples: 



<+>$ 





</>$ 
1 



</ 3.0>$ 

0.33333333 



<- 2>S 
-2 



One arithmetic function that always requires some discussion is the pseudo-random-number 
generator. MDL's is named RANDOM, and it always returns a FIX. uniformly distributed over the whole 
range of FIXes. Example ("pick a number from one to ten"): 



<+ 

4 



1 <M0D <RAND0M> 10»$ 



er 



5.5. Simple Predicates 



The best analogy for a predicate in MDL (or LISP) is the predicate of an English-language question 
such as -Is John taller than Jim?" MDL answers such a question with true or false. If there is no 
other useful information to return, MDL will return T for true (£ la LISP) or #FALSE ( ) for false. 

The MDL predicate 0? takes one argument which can be either a FIX or a FLOAT. It evaluates to T 
only if its argument is exactly equal to or . 0. 

<0? i.2>$ 

#FALSE () 

The predicate 1? evaluates to T only if its argument is exactly equal to 1 or 1.0. The predicate G? 
takes two arguments, which again can be either FIXes or FLOATS. It evaluates to T only if the first 
argument ls algebraically greater than the second. L«? is the Boolean complement of G?; that is it is 
I only if the first argument is not algebraically greater than the second. 

<L-? 3 4>S 

T 

Similarly. L? evaluates to T only if its first argument is algebraically less than its second argument. 
fa=7 is the Boolean complement of L?. 

= a ? takes two arguments of ajiy. TYPE. In the case of arguments which are FIXes or FLOATs. it 
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neveTbJ-'. ; 7a JS? "" "^ """ °' ** ^ FL °" S °' M ,he Mme ^ A FIX ca " 

<■«? 17 17>$ 

T 

<"? 1.0 1>J 

#FALSE () 

To compare a FIX to an equivalent FLOAT, the SUBRs FIX or FLOAT are used: 

<SET A 17>$ 

17 

<SET B 17.0>$ 

17.0 

<-•? .A <FIX .B»$ 

T 

<-■? <FL0AT .A> .B>$ 

T 

N«-? is the Boolean complement of ■■?. 

GASSIGNED7 checks whether an ATOM has been assigned a global value. 

<6ASSIGNED? GAFWEEP>$ 

#FALSE () 

<SETG GAFWEEP 4023>$ 

4023 

<GASSIGNED? GAFWEEP>J 
T 

ASSIGNED? is the corresponding predicate which checks whether an ATOM has been assigned a locai 

and Clwl of f h f" ^f K VAL c 0f ^ AT0MS ' A and B ' Where lhe LVAL °' A h known to be a FIX 
and the LVAL of B is known to be a FLOAT, use the SUBRs FIX or FLOAT; 

<«-? <FL0AT .A> .B>$ 



or 



<■■? .A <FIX .B»$ 
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6. Simple Functions 



6.1. General 

The MDL equivalent of a "program" (uncompiled) is an object of TYPE FUNCTION. Actually, full- 
blown "programs" are usually composed of sets of FUNCTIONS, with most FUNCTIONS in the set 
acting as "subprograms". 

A FUNCTION may be considered to be a SUBR or FSUBR which you yourself define. It is "run" by 
using a FORM to apply it to arguments (for example, <f unction arg-7 arg-2 ... », and it always 
"returns" a single object, which becomes the value of the FORM that applied it. The single object may 
be ignored by whatever "ran" the FUNCTION (equivalent to "returning no value"), or it may be a 
structured object containing many objects (equivalent to "returning many values"). MDL is an 
"applicative" language, in contrast to "imperative" languages such as Fortran. In MDL, it is 
impossible to return values through arguments in the normal case (i.e. "call by name"); they are 
returned normally as the value of the FORM itself, or as side effects to structured objects or global 
values. 

In this chapter a simple subset of the FUNCTIONS you can write is presented, namely FUNCTIONS 
which "act like" SUBRs with a fixed number of arguments. While this class corresponds to about 90% 
of the FUNCTIONS ever written, you won't be able to do very much with them until you read further and 
learn more about MDL's control and manipulatory machinery. However, all that machinery is just a 
bunch of SUBRs and FSUBRs, and you already know how to "use" them; you just need to be told what 
they do. Once you have FUNCTIONS under your belt, you can immediately make use of everything 
presented from this point on in this document. In fact, we recommend that you do so. 



6.2. Defining FUNCTIONS 



<DEFINE SQUARE (X) <• .X .X»$ 
SQUARE 

DEFINE is a MDL FSUBR (remember that FSUBRs have none of their arguments EVALed) for 
defining your own FUNCTIONS. It takes an ATOM as the "name" for the FUNCTION, a list of arguments, 
and the FORMs which make up the body of the FUNCTION. DEFINE SETGs EVAL of itsi first argument 
(the ATOM) to an object of TYPE FUNCTION made Irom the oilier c-.rguments and returns EVAL of the 
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first argument (the ATOM "naming" the FUNCTION). 

If EVAL of DEFINE's first argument already has a GVAL, DEFINE produces an error This helos to 
keep you from accidentally redefining things - such as MDL SUBRs and FSUBRs E*J£ff£ 
able to redef.ne without getting this error, type <SET REDEFINE T> The ATOM snn« F h« k 

essss"* which compu,es the —• - a ^* -«3ebke 

<SQUARE 6>$ 

26 

<SQUARE 1.6>$ 

2.25 

er'ror 9 ^S snliapp "TL!"* ° f ^^ (anything 0ther than a FIX or ™) will produce an 
^k^S^ Wr ° n9 nUmbBr ° f ar9UmentS (anythin9 other than ™> wi " -ho 



Taking the GVAL of SQUARE will show you what a FUNCTION looks like; 



.SQUARES 

#FUNCTI0N {(X) <• .X .X>) 



?i^l^l^^^^^ tto§mmim t« <• -X .X>>. You could define a 
FUNCTION the same way, .f you w.shed, or you could apply the FUNCTION directly: 



<#FUNCTI0N ((X) <• .X .X>) 6>$ 
25 

^FUNCTION ((X) <• .X .X>) 1.6>$ 
2.26 

Obviously, this would become quite tedious. 



6.3. Application of FUNCTIONS: Binding 
mc^^^^Tt^ is happening in each of me *«* in «** **«°n- 

runt i iuns will be applied in the tedious, non-standard method just shown. 
FUNCTIONS, like SUBRs and FSUBRs, are applied using FORMs. So, 



^FUNCTION ((X) <• .X .X>) 6>$ 

26 
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applied the indicated FUNCTION to 6 and returned 26. 

What EVAL does when applying a FUNCTION is the following: 

• 

1. Create a "world" in which the ATOMs of the argument LIST have been §H to the values 
to which the FUNCTION was applied, and all other ATOMs have their original values. This 
is called "binding". (In the above, this is a "world" in which X is SET to 5.) 



an 

.Iso 



2. In that new "world", evaluate all the objects in the body of the FUNCTION, one after the 
other, from first to last. (In the above, this means evaluate <• .X .X> in a "world" 
where X is SET to 6.) 

3. Throw away the "world" created, and restore the LVALs of all ATOMs bound in this 
application of the FUNCTION to their originals (if any). This is called "unbinding". (In the 
above, this simply gives X back the local value, if any, that it had before binding.) 

4. Return as a value the lasj value obtained when the FUNCTION'S body was evaluated in 
step (2). (In the above, this means return 25 as the value.) 

The fact that such "worlds" are separate from the FUNCTIONS which cause their generation means 
that aM MDL FUNCTIONS can be used recursively. (For those of you who understand the term, MDL is 
"dynamically scoped.") 



e a 



an, 



The only thing that is at all troublesome in this sequence is the effect of creating these new 
"worlds", in particular, the fact that the previous world is reslored. This means that if, inside a 
FUNCTION, you SET one of its argument ATOMs to something, that new LVAL will qoJ be remembered 
when EVAL leaves the FUNCTION. However, if you SET an ATOM which is not in the argument LIST 
(or SETG any ATOM) the new local (or global) value will be remembered. Examples: 

<SET X 0>$ 



<#FUNCTI0N ((X) <SET X <• .X .X») 6>S 

26 

.X$ 

o 

On the other hand, 

<SET Z 0>$ 



<#FUNCTI0N ((X) <SET Z <• .X .X») 6>$ 

26 

.ZS 

26 
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%S2L!S£:!g£r ,,see " ,ha ' an ar9umen, ' s LVAL rea,,y is chan9ed while 

<SET X 6>$ 
6 

<#FUNCTI0N ((X) <PRINT .X> < + .X 10>) 3>$ 
3 13 

.xs 

6 
ISicalon mber ^^ Ule apP ' icati0n F0RM was **>«> out b * * e '"NT; the second is the value of the 

JSSSS!^ AT0MS ** in ar9umem LISTs - - chan ^ « - ■*— 

<SET Z 100>$ 
100 

<#FUNCTI0N ((Y) </ .Z .Y>) 6>J 
20 

ATOMs used like Z in the above examples are referred to as "free variables" The use of free 
vanables, wh.le often quite convenient, is rather dangerous unless you know « how a FUNCT ol 

FUnS^ 3 FU ? C ! 10 " COn,ainin9 ' ree Variab,6S iS US6d withtf^UNCTION S a 

2?lbT^? ^ FUNCTI0Ns might iust happen t0 use your free variab,e in to 
argument LIST, binding it to some unknown value and possibly causing your use of it to he 

^Xo^z^zr^ to use your functions - and (2) for ■ to «- *<- ««5 a 



6.4. DEFINEing Some Simple FUNCTIONS 

Using SQUARE as defined above, let's DEFINE a FUNCTION to compute the length of the 

hypotenuse of a right triangle given the lengths of the two sides: 

<0EFINE HYPOT (SIDE-1 SIDE-Z) 

<SQRT <+ <SQUARE .SIDE-1> <SQUARE .SIDE-2»»$ 
HYPOT 

<HYP0T 3 4>$ 
6.0 



SIMPIF FUNCTIONS SECTION 6.3 



IMEP 



THE MDL PRIMER 31 



;nce 



.- SORT is the SUBR which returns the square root of its argument. It always returns a FLOAT. 

A whimsical FUNCTION: 

<0EFINE ONE (THETA) 

<+ <SQUARE <SIN .THETA» 
<SQUARE <C0S .THETA»»$ 
ONE 

<0NE 6>$ 
0.99999994 
<ONE 0.23>S 

0.99999999 

fthe 

ONE always returns (approximately) one, since the sum of the squares of sin(x) and cos(x) is unity for 
any x. (SIN and COS always return FLOATs. and each takes its argument in radians. ATAN 
(arctangent) returns its value in radians. Any other trigonometric function can be composed from 
these three.) 

MDL doesn't have a general "to the power" SUBR, so let's define one using LOG and EXP (log base 
e, and e to a power, respectively; again, they return FLOATs). 

<DEFINE •• (NUM PWR) 

<EXP <• .PWR <L0G .NUM»»$ 

free 

ION <•• 2 2>$ 

lin a 4.0000001 

<•• 6 3>$ 
125.00000 
<•• 26 0.6>$ 
6.0000001 

Two FUNCTIONS which use a single global variable (Since the GVAL is used, it cannot be rebound.); 
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<DEFINE START () 

<SETG GV 0»$ 
START 
<OEFINE STEP () 

<SETG GV <+ ,GV 1>»$ 
STEP 

<START>S 


<STEP>$ 
1 

<STEP>$ 
2 

<STEP>$ 
3 

START and STEP take no arguments, so their argument LISTs are empty. 
An interesting, but pathological, FUNCTION: 



<DEF 

INC 

<SET 



<INC 

1 

<INC 

2 

.AS 

2 



INE INC (ATM) 

<SET .ATM <+ ..ATM 1>»$ 

A 0>$ 

A>$ 

A>$ 



INC takes an fiJOM 3S an argument, and SETs that ATOM to its current LVAL plus 1. Note that inside 
INC, the ATOM ATM is SET to the ATOM which is its argument; thus . .ATM returns the LVAL of the 
argument. However, there is a problem: 

<SET ATM 0>$ 



<INC ATM>J 

•ERROR* 
ARG-WRONG-TYPE 

+ 

LISTENING-AT-LEVEL 2 PROCESS 1 
The error occurred because .ATM was ATM, the argument to INC, and thus . .ATM was ATM also. We 
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really want the outermost . in . .ATM to be done in the "world" (ENVIRONMENT) which existed iust 
before, INC was entered -- and this definition of INC does both applications of LVAL in its own 
"world". 



6.5. Pretty-Printing 

In MDL, carriage-returns, linefeeds, tabs, etc.. are just separators, like spaces. At least one space 
is needed between MDL objects, but there is no maximum number. 



81 



3 



4>$ 



Using only one space at all times results in code which is effectively unreadable. This is even 
demonstrable with tiny FUNCTIONS similar to the ones created in this chapter. For example: 

<DEFINE ZERO (THETA) 

<- <+ <SQUARE <S1N .THETA» 

<SQUARE <C0S .THETA>» 

<+ <SQUARE <SIN .THETA» 

<SQUARE <C0S .THETA>»»$ 
ZERO 

Typing , ZEROS to MDL will cause it to return: 

#FUNCTI0N ((THETA) <- <+ <SQUARE <SIN .THETA» <SQUARE <C0S 
.THETA>» <+ <SQUARE <SIN .THETA» <SQUARE <C0S .THETA»») 

Long FUNCTIONS printed like this would be very difficult to read. MDL has a "pretty-printer" (for full 
details see The MDL Programming Environment [Lebling 80]) f called PPRINT which prints functions 
with spacing similar to the examples in this chapter. 

<PPRINT ZER0>$ 

<0EFINE ZERO (THETA) 

<- <+ <SQUARE <SIN .THETA» <SQUARE <C0S .THETA>» 
<+ <SQUARE <SIN .THETA» <SQUARE <C0S .THETA»» 

The general idea behind MDL pretty printing is: if all the arguments to a function fit on one line they 
are printed on one line, if not, arguments are printed on successive lines indented by the same 
amount. This allows you to see the level of "nesting" at a glance, and makos it easier to see what is 
happening. 
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6.5.1. Editors and Pretty Printing 



recommended , ha. ^u geU t he S T^m^'TI " P"** - S ' y ' e - " iS «™** 
more easily understood by o"hers and monHm '"* ,°°L S '^ ,he beQinnin9 ' Your code *■ * 
BracKe.balancinQalsoh.roml' I :^°7™ POr,an,ly '. by ^ *»*ral "»"»» after you write it. 



BracKe, ba,ancin g aiso becomes ^S^ZXJSSSZ 



quite rare. 



6.6. Loading a File 

If you nave a MOL program in a file, you can "load" it by typing H 

<FLOAD We>% 

<FLOAD »ZERO">$ <FLOAD "ZERO.MUD">$ 

computations are not printed V^^SS h^ LT? ** " ValUeS " pr0duced b * lhe 
pnniea. wnen MDL is finished processing the file, it will print "DONE". 

llST Z^^SSS t£S ZER °; h HUD ' ^ * - ,he "^ °" e «""- • 
"ZERO. MUD. 69106"». SPeC '" Ca " y mCluded '" the argument to FLOAD (e.g. <FLOAD 



When MDL starts running, it will FLOAD the file "Mlinni c tutt- rr— 
exists. This allows you to have vourwnrkiln HUDDLE -J NIT Oenex and Tops-20 versions), if it 
when you begin a session It X a L 9 " a " y °' her ""* y0U WiSh loaded int0 * our M °l- 
redefining FUNCTIONS etc ^ '° CUS,omize " vour MDL by setting certain flags. 
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7. MDL TYPEs 



In Chapter 2, we provided an introduction to the MDL TYPE system. This chapter will expand on 
that introduction and explain the creation of user-definable MDL TYPEs. 



7.1 . TYPEs and PRIMTYPEs 

In Chapter 2 it was stated that every MDL object has a TYPE. The SUBR TYPE, given a MDL object, 
returns an ATOM which is the name of the object's TYPE. 

<TYPE 12>$ 

FIX 

<TYPE (1 2 3)>$ 

LIST 

In MDL, each TYPE can be thought of as a member of a smaller number of more 'primitive' TYPEs. In 
MDL, these 'primitive' TYPEs are known as PRIMTYPEs. Just as every MDL object has a TYPE, so 
every MDL object has a PRIMTYPE. A SUBR called PRIMTYPE, given a MDL object, returns an ATOM 
which is the name of the object's PRIMTYPE. 

We have already seen examples of a number of MDL PRIMTYPEs without ever mentioning the 
notion of PRIMTYPE. Here are the most important PRIMTYPEs in MDL. 

-WORD - the PRIMTYPE of all FIXes, FLOATS, and CHARACTERS. Any MDL object which 
can be thought of as a number will be of PRIMTYPE WORD (CHARACTERS are internally 
stored as their ASCII values). 

- ATOM - the PRIMTYPE of ATOMs. 

- LIST - the PRIMTYPE of LISTs. FORMs, and FALSEs. 
• VECTOR ■ the PRIMTYPE of VECTORS. 

- STRING • the PRIMTYPE of STRINGS. 
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7.2. Introduction to MDL Structures 

As we saw in Chapter 2, MDL objects may be either structured or not. A Structure can be thought 
of as an ordered series of MDL objects. MDL has a number of different 'classes' of structures, each 
with different properties. These 'classes' are the structured PRIMTYPEs: LIST, VECTOR, and STRING. 
In Chapter 2, it was also noted that matching brackets are used to represent these structured objects. 
Each of the structured PRIMTYPEs has its own unique bracket type by which it can be identified. The 
brackets used for the structured PRIMTYPEs are as follows: 

- LIST - matching parentheses 

- VECTOR • matching square brackets 

- STRING - paired double quotes 

<SET A (1 2 3)>$ 

(1 2 3) 

<TYPE .A>$ 

LIST 

<TYPE <TYPE .A»$ 

ATOM 

<PRIMTYPE .A>$ 

LIST 

<SET B <+ 1 2»$ 

3 ; "0op$ I" 

<SET B *<+ 1 2»$ 

<+ 1 2> ;"That's betterl" 

<TYPE .B>$ 

FORM 

<PRIMTYPE .B>$ 

LIST 

In the example, notice that the FORM <+ 1 2> will get evaluated in the call to SET. In order to SET B 
to the FORM instead of the result of its evaluation, a single-quote is placed before the FORM. The 
single-quote tells MDL not to evaluate the following object. 



7.3. The TYPE? Predicate 

The SUBR TYPE? can be used to check the TYPE of a given object against a particular set of TYPE 
names. TYPE? takes a MDL object and any number of ATOMs, which must each be the name of a MDL 
TYPE. If the object is not one of those TYPE names given, TYPE? relurns #FALSE (). Othenwise.it 
returns the TYPE of the object. 
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<TYPE? 10 ATOM VECT0R>$ 

#FALSE () 

<TYPE? 10 FIX FLOAT AT0M>$ 

FIX 



7.4. Printing of MDL Objects 

In general, the printing of a MDL object is dependent on the PRIMTYPE of that object. MDL objects 
will usually be printed as follows: 

ttype-name ob/ecf-as-/7-PRIMTYPE 

Usually, if the TYPE of the object and the PRIMTYPE of the object are not the same, the number-sign 
and type-name are printed. There are a few exceptions to this: the TYPEs FIX, FLOAT, CHARACTER, 
and FORM all print in a more simplified manner because of their common use. 

We have already seen an example of this 'number-sign notation' with the TYPE FALSE. You may 
have noticed that it prints as a number-sign, the ATOM FALSE, and an 'empty' LIST. The meaning of 
this is that FALSEs are of PRIMTYPE LIST: the #FALSE must be used in both input and output to 
distinguish the object from objects of TYPE LIST. In general, you can tell the PRIMTYPE of an 
unknown type in 'number-sign notation' by looking at the part after the type-name. If it has square- 
brackets, it's a PRIMTYPE VECTOR. Parentheses, it's a PRIMTYPE LIST. Etc. 

<PRIMTYPE #TABLE [1 2 3]>$ 

VECTOR 

<PRIMTYPE #TEXT M ABCDE">$ 

STRING 

<PRIMTYPE #NUMBER 10> 

WORD 

Note that the TYPEs TABLE, TEXT, and NUMBER are not defined in MDL; a user might have created 
them, however (see later), and their PRIMTYPEs are obvious from the part after the type-name. 



7.5. Significance of PRIMTYPEs / CHTYPE 

The notion of PRIMTYPE is very important. The PRIMTYPE of an object tells MDL what the object 
looks like internally to MDL. As far as MDL is concerned, any two objects of the same PRIMTYPE are 
more or less interchangeable (e.g. most SUDRs which can be used on LISTs can aso be used on 
FALSEs.) 
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This notion of interchangeability is a very powerful one. In fact, MDL allows you to arbitrarily 
change the TYPE of virtually any MDL object to another TYPE, as long as objects of that other TYPE 
have the same PRIMTYPE as the original. The SUBR which 'changes' TYPEs is called 
CHTYPE (pronounced 'chitype'). It takes a MDL object and the name of a TYPE (ATOM) and returns 
the MDL object 'changed' to that TYPE. 

<CHTYPE (+ 1 2) F0RM>$ 
<+ 1 2> 

<CHTYPE (A B C) FALSE>$ 
#FALSE (A B C) 
<CHTYPE 2.5 LIST>$ 

•ERROR* 

STORAGE-TYPES-DIFFER 
CHTYPE 

LISTENING-AT-LEVEL 2 PROCESS 1 

Often one would like to know what the PRIMTYPE of an object of a certain TYPE would be. This can 

DDT™ 0U . t by USin9 thS SUBR TYPEPRIM: Siven a name of a TYPE, it returns the name of the 
PRIMTYPE of objects of that TYPE. 

<TYPEPRIM FALSE>$ 

LIST 

<TYPEPRIM FL0AT>$ 

WORD 

To restate the conditions for a successful CHTYPE in terms of TYPEPRIM: the PRIMTYPE of the first 
argument must be the same as the TYPEPRIM of the second. Isn't that much clearer? 



7.6. Creating new TYPEs 



Given the interchangeability among objects with the same PRIMTYPE, it should not be surprising 
'?' ^^l 3 "™ you t0 create aR y arbitrar V new TYp E. so long as you define It to have a known 
mul PRIMTYPE. The SUBR which creates new TYPEs is, not surprisingly, NEWTYPE. NEWTYPE takes 
an ATOM (the name for your new TYPE) and the name of the TYPEPRIM lor that new TYPE (also an 
ATOM). It returns rts first argument. NEWTYPEs will defaultly print out (and can be read back) in 
number-sign notation'. 
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<NEWTYPE TABLE VECT0R>$ 

TABLE 

<SET X #TABLE [JOE 1 JOHN 2]>$ 

#TABLE [JOE 1 JOHN 2] 

<CHTYPE .X VECTOR>$ 

[JOE 1 JOHN 2] 

There are only two ways to create an object of a user-defined TYPE: type the object in directly (as 
was done in the previous example) or to usetheSUBR CHTYPE explicitly. 



<CHTYPE [JIM 2 JANE 4] TABLE>$ 
#TABLE [JIM 2 JANE 4] 
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8. MDL Structures 



As we saw in Chapter 2, MDL objects may be either structured or not. It was stated that structures 
can be thought of as ordered series of MDL objects and that different classes of structures existed. In 
this chapter we will describe the common structures used in MDL. 



8.1. Equality 






It is necessary here to mention the notion of equality. In MDL, there are two types of equal: double- 
equal and single-equal. The SUBRs which represent these concepts are «7 and ■?, respectively. 
Simply stated, two MDL objects which are the same thing are double-equal. Two objects which look 
the same, i.e. are printed the same way, are single-equal. This confusing distinction is unimportant 
for objects which aren't structured. Two non-structured objects which print the same are the same. 
For example, there is one and only one MDL object representing the FIX 19. However, one can 
easily build two structures at two different times which look the same, but which are not the same. 
This will be explained below in the discussion about LISTs. As an example of the use of =?, assume 
that you have written a program which takes some input from the user and wants to see if he typed the 
word F00. Let's assume an input routine called INPUT which returns a STRING. 



<SET STR <INPUT»$ 

"F00" 

<■■? .STR "F00">$ 

#FALSE () 

<■? .STR "F00">$ 

T 

This is because the two STRINGS were not identical; they look the same, however, and therefore are 
B ?. Figure 8- 1 purports to demonstrate the distinction between types of equality. 



8.2. PRIMTYPE LIST 

MDL objects of PRIMTYPE LIST may be thought of as an ordered series of MDL objects, whose 
connective link is a 'pointer'. This means that in order to find the Nth element of a LIST one must 
look at each of the previous N-1 elements. This is shown in Figure 8-2 This becomes rather tedious 
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The representation of a MDL object is: 



<*yp«> j 



<«algt> 



Zl's'ZZ^. TYPE °' ^ "*« - «*"> * » «"** ** —are, 






Fl X 


1 




A - 
B - 
C - 
- 

E - 
F — 




1 















LIST 




E 


10 

(10) 
(KJ) 
00) 




* 


FIX | 




10 






1 LIST 






10 


1 


™ *■ I r i v 




K> 




f ■ 


D 




LIST 




I 

























Definition: 

Question: 
Answer: 

Question: 

Answer: 



Two MDL objects are «? if and only if the <type> and 
<value> parts are the same. They are -? if they look the 

Are any of B, C, or D «? to each other? 

C and D. They have the same TYPE and point to the same 
structure. B and C are ■?. as are B and D - they 1^ tffe 
but are not identical. ^"^ 

Are any of A, E. or F «? to each other? 

They are aii «? to each other. 



SSSt£i 1 c I"' T L n ° ti0n ° f equa,ity is d^nonatrated in this figure, 
which shows the distinction between single-equal .? and double-equal 

■■?. 
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when one is interested in finding the 245th element of a LIST. You can see that large LISTs have the 
property of being rather inefficient to 'random-access'. On the other hand, LISTs can easily be 
modified (adding elements, removing elements, etc) simply by changing the linking 'pointers'. In 
Figure 8-3 you can see pictorially how an element of a LIST might be removed. Notice that the 
removed element still 'exists', but that the LIST is no longer 'pointing' at it. 



Two SUBRs which should be mentioned here are LENGTH and EMPTY?: the first, given a LIST, 
returns the number of elements in that LIST (as a FIX), and the second, given a LIST, returns the 
ATOM Tor#FALSE (), i.e. whether the LIST had no elements. 







P 1 A | 




1 









r 1 a | 




2 





FIX 



Figure 8-2: The LIST (1 2 3) 



F I X 




F I X 



Fl X 



This LIST is now (1 3). 



Figure 8-3: Removing a LIST element by moving only one pointer 



8.2.1. Creating LISTs 

Creating a LIST is very simple. Simply type in the printed representation of it, which (as described 
before) is a series of MDL objects surrounded by parentheses. 
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<S£T A (1 TWO 3.0)>J 
(1 TWO 3.0) 
<SET B (A .A C)>$ 
(A (1 TWO 3.0) C) 

Using this method, every MDL object olaced hPtwpon th* ~«»~ht- 

LVAL of A was placed in the LIST * atCh ' nQ parenlheses * EVALed. Thus, the 

<SET B (X Y Z)>$ 
(X Y Z) 
<LENGTH .B>$ 
3 

<EMPTY? .B>$ 
#FALSE () 

SS E EMPTY? (UST) <W " ? <LENGTH - LI ST> 0»$ 
fcMPTY i 

- 

The and of the previous exampie gives a definition of EMPTY? in MDL, given onlv ,ne SUBRs LENGTH 

<SET A <LIST 1 TWO 3.0»$ 
(1 TWO 3.0) 

In both methods, anew LIST is created. 

<SET A (1 2 3)>$ 

(1 2 3) 

<SET B (1 2 3)>$ 

(1 2 3) 

<"? .A .B>$ 

#FALSE () 

<■? .A .B>$ 

T 
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8.2.2. EVALing LISTs 

LISTS, when EVAled, make a new copy of the LIST with ail of the elements re-EVALed. 

<SET A (1 2 3)>$ 
(1 2 3) 

<■■? <EVAL .A> .A>$ 
#FALSE () 



8.2.3. Manipulating LISTs 

In order to discuss LISTs more fully, we need to know a few ways to manipulate them. We will 
introduce two SUBRs here, NTH (pronounced 'enth') and REST. The SUBR NTH. given a LIST and a 
FIX, will return the FIXth element of the LIST. REST, given a LIST and a FIX, will return the LIST, 
with the first FIX elements at the beginning removed. The second argument to both NTH and REST 
has a default value of 1. Some examples: 

D)>$ 



<SET 


L (A B C 


(AB 


C D) 


<NTH 


.L 3>$ 


c 




<NTH 


.L 2>$ 


B 




<SET 


LL <REST 


(C D] 




<RES1 


.L 4>$ 







.L$ 




(A B 


CD) 



.L 2»$ 



Notice that REST has no side-effects. In other words, it simply returns a pointer farther down the 
'chain' of elements in the LIST without changing anything. This is illustrated in Figure 8-4. Another 
important operation on LISTs is called PUT. As its name suggests. PUT puts an element into a LIST. 
Given a LIST, an element number (FIX, as in NTH), and an arbitrary object, PUT makes the FIXth 
element of LIST become that object, and returns the LIST. Let's continue from the example given in 
Figure 8-4 with L and LL already defined. 

<PUT .LL 1 HAHA>$ 

(HAHA D) 

.LS 

(A B HAHA D) 

What happened hore is shown in Figure 8*5. Since LL was a 'subset' of L, any crwnge in LL was 
reflected in L (Ihe oppose would also be true, i.e. a PUT into the third or fourth elements of L would 
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<SET L (A 8 C D)>$ 
(A B C 0) 




Notice that the LIST (C D) is a subset of the LIST (ABC D) because of 
the way REST works. 



Figure 8-4: REST of a LIST 



be reflected in LL.] 







The only effect is that the contents of the third element was changed, 
from 



moved. 



itomI 


10 


atom) 


c 


HAHA 



No pointers have 



Let's continue: 



Figure 8-5: PUTs into LISTs 
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<SET 


M .L>$ 




(A B 


HAHA D) 




<SET 


L (1 2 3 


»S 


(1 2 


3) 




.MS 






(A 8 


HAHA 0) 




.LL$ 






(HAHA D) 




<•«? 


<REST .M 


2> 


T 
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.LL>$ 



If you understand this, good. Otherwise, pay close attention to Figure 8-6. in which this example is 
diagrammed. It is of crucial importance that the distinction be learned between a structure and a 
pointer to a structure. Changing a structure (e.g. with PUT) will be reflected in any object which 
points to it. Changing the pointer to a structure doesn't affect any other pointers. If you don't 
understand this distinction, you will probably become more and more lost. Ask someone for help. 







<SET H ■ l> made H point to where L pointed at that time . 

<SET L (1 2 3)> merely pointed L somewhere else. 

The values of H and LL are noj affected, then, by reSETting L. 



Figure 8-6: Pointers vs. Structures 



Now things get a little more complex. However, if you understood the previous examples, this should 
be no different. Earlier, we talked about 'moving' pointers to effect removal of objects from a LIST. 
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This movement can be accomplished in MDL using the SUBR PUTREST. PUTREST (equivalent to 
Lisp's replacd) is probably the most confusing SUBR to beginners, and even to accomplished MDlers. 
Its effect is very simple: given two LISTs, say A and B, it causes the REST of A to become B, and then 
returns A. This probably sounds very obscure. Before total confusion sets in, take a look at the 
example and then at Figure 8-7. 



<SET A (1 2 


3)>$ 


(1 2 3) 




<SET B (4 6 


e)>$ 


<PUTREST .A 


.B>$ 


(14 5 6) 




M 




(4 6 6) 





All that has happened is that one pointer has been moved: the one connecting the first element of A to 
its succeeding element has been changed to a pointer to B. That's all. Notice that any object which 
points to the same place that A points has been changed. However, also notice that any object which 
points to the REST of A has not been changed. 



<PUTREST .A ,B> 




F IX 


• 


3 




FIX 


• 


6 



Only one pointer has been moved. A is changed, but 8 is not Notice that a 
hypothetical C, previously SET to REST of A, is also not changed. 



Figure 8-7: PUTREST 



Using PUTREST, it is easy to remove elements from a LIST. 
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<SET A (1 2 3 4)>$ 
(12 3 4) 

<PUTREST .A <REST .A 2»$ 
(13 4) 

What we have done is to make the first element of A (1 in the example) point to the value of A RESTed 
twice. This is demonstrated in Figure 8-8. 



<PUTREST .A <REST .A 2» 









P IA ] 




3 





F IX 



The REST of A has become A RESTed twice. The effect is to remove the FIX 
2 from the LIST. 



Figure 8-8: Removing an element from a LIST using PUTREST 



Notice that you can not use this method to remove the first element of a LIST, since PUTREST only 
changes the pointer which connects the first element to the second element. However, one can 
always use REST for this purpose, but be careful: 

<SET A (1 2 3 4)$ 

(12 3 4) 

<REST .A>$ 

(2 3 4) 

.AS 

(12 3 4) 

As we noted earlier, REST has no side-effects, unlike PUTREST, which does. The right thing to do is 

<SET A <REST .A»$ 
(2 3 4) 

-AS 

(2 3 4) 

One can cause a LIST to terminate at any point by giving PUTREST a second argument of an empty 
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LIST. 



<SET A (1 2 3 4)>$ . 
(12 3 4) 
<PUTREST .A ()>$ 

(1) 

As advertised, the REST of A has been made the second argument to PUTREST, i.e. the empty LIST. 

To combine LISTs, one can use PUTREST also. Try to think of how you would combine the LISTs 
in the following example. Think pointers. 

<SET A (1 2 3)>$ 
(1 2 3) 

<SET B (4 6 6)>$ 
(4 6 6) 

The idea is to make the third element of A (the FIX 3) to point to the LIST B. In terms of PUTREST, 
we want B to become the REST of which LIST? The answer is 

<PUTREST <REST .A 2> .B>$ 

(3 4 6 6) 

.AS 

(12 3 4 6 6) 

PUTREST returned its first argument, which was A RESTed twice. A. however, was changed. Refer to 
figure 8-9 if confused. 



O-E 



[XI 





CRUT.A1 > 




J 




irmi - 




FIX| •- 


2 


3 




s 



FIX 



UH 



<PUTREST <REST .A 2> .B> 



n*T_ 



Figure 8-9: Splicing LISTs together using PUTREST 
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With your new-found expertise in PUTRESTing, you should take a moment and think about how you 
would build a LIST backwards. For example, you wish to append the FIX 7 to the LIST from the last 
example. What is the correct MDL expression? Hint: You have to create a LIST with the FIX 7 in it. 

<PUTREST <REST .A 6> (7)>$ 

(6 7) 

.A$ 

(12 3 4 6 8 7) 

Here are some problems to think about 

<SET L (1 2 3 4)>$ 

(12 3 4) 

<SET LL <REST .L 1»$ 

(2 3 4) 

<SET LLL <REST .L 2»$ 

(3 4) 

<PUTREST <REST .L> <REST .L 3»$ 

(2 4) 

What are the LVALs of L, LL, and LLL now? 

<SET WALTZ (2 3 1)>$ 

(2 3 1) 

<PUTREST <REST .WALTZ 2> .WALTZ>$ 

If you try this, be ready to type tS.' What has happened? What is the LENGTH of L now? Why 
shouldn't you try to find out? Why is this a waltz? 

<SET ONES (1 2 3)>$ 
(1 2 3) 

<PUTREST .ONES .0NES>$ 

What about this? 

The last two examples demonstrate an important notion, that of circularity. There is absolutely no 
restriction on the creation of circular and self-referencing structures. However, you should be sure 
you know what you're doing. For example, finding the LENGTH of ONES or of WALTZ in the previous 
examples is quite time-consuming. The SUBR called LENGTH? can be of use here. Given a LIST and 
a FIX. LENGTH? will return the LENGTH of the LIST if it is less than or equal to FIX. Otherwise, it will 
return #FALSE ( ). This is useful if you suspect a LIST is self-referencing or to check on whether a 
LIST is at least a certain length. For example, prior to trying to get the 12th element of a LIST of 
uncertain size, one might check that 

(LENGTH? .LIST 11> 
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returned #FALSE ( ) , i.e. there are at least 12 elements in the LIST. 



8.2.4. FIXes First in FORMs 

*l^~MmT£^£E£ w v se GVAL is a "*■ ,his is considered to * * 

Thus, the fo„owin 9 two !2Kfi3 33fi " "" " "" ar9Umen ' S ' "^'^ 

<il .FOO> 
<NTH .FOO 11> 

So are these: 

<11 .FOO .BAR> 
<PUT .FOO 11 .BAR> 

Here is an example of an ATOM being used first in a FORM with the same effect: ' 

<SET L (FOO BAR BLETCH)>$ 
(FOO BAR BLETCH) 
<SETG FIRST 1>$ 

<SET6 SECOND 2>$ 

2 

<FIRST .L>$ 

FOO 

<SEC0ND .L>$ 

BAR 

<FIRST .L FR0B>J 

(FROB BAR BLETCH) 



8.2.5. FORMs 



which can be done on LISTs can be done on them «KhL " nd a " °' lhe °P era,i °"s 

creating a FORM by inputting elements betwee anoleh J 1 ,?" "*■ eVah " ,9d ''" * Special wa * 
true if you are using the SUBR FORM W " reqU ' re a sin 9 lec l"°<e- This is not 
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<SET A <+ 1 2 3»$ 

8 

<SET A '<+ 1 2 3»$ 

<+ 1 2 3> 

<SET A <F0RM + 1 2 3»$ 

<+ 1 2 3> 

A special note should be made of the empty FORM: it evaluates to an empty FALSE. This is simply a 
shorthand notation. 



<>$ 

#FALSE () 



8.2.6. FALSEs 

Previously, you have seen examples of MDL objects of TYPE FALSE. All of them thus far have 
been EMPTY?, although this is not always the case. MOL objects of TYPE FALSE are PRIMTYPE 
LISTs and, as has been stated before, can be used in the same ways as any other PRIMTYPE LIST. 
In particular, one can create FALSEs with any number of arbitrary elements. One use of this might be 
to distinguish between two types of failures in a function. Thus, the FALSE can have two types of 
meaning: its TYPE (which is FALSE) and its contents. One might simply want to detect failure by 
checking the TYPE, but one might additionally want to detect failure and also have other information 
about the failure available. 

<SET VAL <0PEN "READ'' "F00.BAR ,, »$ 
#FALSE ("File not found" "FOO.BAR" 69106) 
<1 .VAL>$ 
"File not found" 

• 

In this example, the SUBR OPEN was called in an attempt to open a file called FOO.BAR. The OPEN 
failed, and returned a FALSE which contained three pieces of information: the reason (a STRING), the 
file name (a STRING), and an internal error code (a FIX). One might have written a FUNCTION using 
OPEN which only cares if OPEN returns a FALSE or not. On the other hand, one might want to print out 
the reason for the failure to the FUNCTION'S user. This would have been impossible had FALSEs not 
been able to carry additional information. As you will Find when doing your own programming, this is 
a significant feature of MDL 



8.2.7. SEGMENTS 

A SEGMENT is a PRIMTYPE LIST, which is handled very specially by MDL. SEGMENTS print as an 
exclamation point followed by a FORM. When EVALed inside an expression, its meaning is as follows: 
pretend that instead of using this SEGMENT, use instead all of the elements you get from EVALing the 
FORM. There is an important implication here: that the FORM, when EVALed, returns a structure. An 
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error will occur if this is not the case. Here are some examples: 

<SET A (1 2 3)>$ 

(1 2 3) 

<SET B (I. A 4 6 8)>$ 

(12 3 4 5 8) ;"Th1s 1s a new 11st, not shared with A" 
<SET C (t.A I.B 7)>$ 

(12 3 12 3 4 6 6 7) ;"No sharing here, either" 

<+ I.A>$ 
6 

<SET L (BAR 10)>$ 

(BAR 10) 

<SET I.L>$ 

10 

.BARS 

10 

This last example is quite pathological: note, however, that it is perfectly legitimate. The FORM was 
read by MDL as having two elements, the ATOM SET and a SEGMENT. When the FORM was EVALed 
the SEGMENT acted as if it was really all of the elements of .L. i.e. the ATOM BAR and the FIX lo! 
This is simply the case of SETting BAR to 10. 

One last very important note: There is one way to add elements to the beginning of a LIST without 

copying. This is the case in which a SEGMENT is the last element of a LIST and the SEGMENT'S FORM 

EVALs to a LIST. In this case only, there is no copying and the structures will share. This is similar to 
CONS in LISP. 

<SET L (F00 BAR BLETCH)>$ 

(F00 BAR BLETCH) 

<SET LL (1 2 3 |.L)>$ ; "The last element 1s a SEGMENT which 

evaluates to a LIST" 
(12 3 F00 BAR BLETCH) 
<PUT .LL 4 SHARED>$ 
(12 3 SHARED BAR BLETCH) 
■ L$ 
(SHARED BAR BLETCH) 

LISTs are the most appropriate structure to use when elements are going to be added or removed 
The special use of SEGMENTS shown in the last example is the best way of adding elements to the 
front of a LIST. However, the resulting LIST will be 'backward', in that the most recently added 
element will be at the 'front' rather than at the 'back' of the LIST. Later on. we will demonstrate the 
correct way to add elements to the end of a LIST. As an exercise, see if you can figure out a method 
for doing so using PUTREST. 
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Remember that (he previous use of SEGMENTS is an exception: in the case of objecls of PRIHTYPE 
VECTOR and STRING (next sections) the use of a SEGMENT will cause copying of the elements from 
the structure which is the EVALuation of the FORM. 



8.3. PRIMTYPE VECTOR 

A MDL object of PRIMTYPE VECTOR can be thought of as a linear array of MDL objects. In a 
VECTOR, it is trivial to access the Nth element, as this simply requires finding the correct offset into the 
structure (see Figure 8-10). Similarly, it is trivial to replace the Nth element with something else. On 
the other hand, there is no way to add elements to a VECTOR without creating a new one, and 
removing elements can be simulated, although it is rather difficult. If your eyes skipped back to the 
section on PRIMTYPE LIST, you might notice that these properties of the two PRIMTYPEs are 
reversed. This, then, is the rationale for having different structure 'classes'. The programmer is free 
to choose the structure 'class' (i.e. PRIMTYPE) he wants, based on the way in which it is to be used in 
a program. For example, a structure which is always of known length should probably be a VECTOR, 
while one which must undergo changes in size should probably be a LIST. 

Schematic representation of a VECTOR 



[12 3 4] 



FIX 






1 




FIX 






2 




FIX 






3 




FIX 




4 





Figure 8-10: The VECTOR [12 3 4] 



8.3.1. Creating VECTORS 

Creating a VECTOR is completely analogous to creating a LIST. There are two options: you can 
type in the printed representation ol a VECTOR, or you can use the SUBR VECTOR. 
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<SET A [1 2 3]>, 

[1 2 3] 

<SET B <VECTOR i 2 3 »$ 

[12 3] 

<"■? .A ,B>$ 

iFALSE () 

<•? -A .B>$ 

T 

<SET C [.A |.B]>$ 

CC1 2 3 3 1 2 3] i-Cdoosufil share with Bl" 



KSar^tT — a "" VEC ™ "•** two obieot 



s created in separate calls 



8.3.2. EVALing VECTORS 

nZT LISTS ' EWL °' 3 VECT ° R "•— * - «» o, the VECTOR. wi, h a., o. the events 

<SET A <EVAL .A»$ 
[3 3 <+ 1 2>] 
<EVAL .A>J 
[3 3 3] 



8.3.3. Manipulating VECTORS 

<SET A [ONE TWO 3]>$ 
[ONE TWO 3] 
<NTH .A 2>$ 
TWO 

<PUT .A 3 THREE>$ 
[ONE TWO THREE] 
.AS 

[ONE TWO THREE] 



mdl f;mucTunES 



SECTION 8.3 



THE MDL PRIMER 



57 



< LENGTH .A>J 

3 

<REST .A 2>$ 

[THREE] 

.AS 

[ONE TWO THREE] 



RESTing VECTORS is shown in Figure 8-11. 




<SET B <REST .A 2» 




3 



Fl X 






I 




FIX 






2 




Fl X 






3 




Fl X 






4 





Figu re 8-11: REST of a VECTOR 



Since VECTORS are not pointer structures, the PUTREST operation will not work on them. However, 
there are a few operations which are possible with VECTORS which are not possible with LISTs due to 
their structure. The first of these is the inverse of REST: it is called BACK. Given a VECTOR and a FIX, 
it tries to replace elements to the front of the VECTOR which were previously RESTed off. Like REST, 
BACK has no side-effects. It simply returns a pointer to a different location in the VECTOR. An error 
will occur if you attempt to BACK more elements than have been RESTed- The SUBR TOP, however, 
given a VECTOR, will BACK as far as is legally possible. 



<SET A [i 2 3 4]>$ 

[12 3 4] 

<SET B <REST .A 2»$ 

[3 4] 

<PUT .8 1 HAHA>$ 

[HAHA 4] 

.A$ 

[1 2 HAHA 4] 



;"B 1s a subset of A" 
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r 



<BACK .B>$ 
[2 HAHA 4] 
• BJ 

[HAHA 4] 

<T0P .B>$ 

[1 2 HAHA 4] 

<"? <TOP .B> .A>$ 

T 



;"BACK has no side-effects' 



BACKing of VECTORS is diagrammed in Figure 8-12. 



SET B <BACK .B 2» 



• u *.S 




FIX 




I 


s~s 


FIX 




l fi 


2 


v — y 


FIX 






3 




I 


FIX 











Figure 8-12: BACK of a VECTOR 



8.3.4. UVECTORs 

«1S a PRIHTYPE caned UVECTOR, for Uniform VECTOR. 

the ^ TYPE. ^SS^^^S^^ **"** °' * UVECT ° R mUSt have 
paired square brackets. m^lSSSSS^ " " eXC ' amati ° n P ° !nI ,0 "° Wed by 
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<SET A I [A B C]>$ 

I[A B CI] ; n Don't worry about the other I before the ]" 

<i .A>$ 

A 

<REST .A 2>$ 

l[C!] 

Analogously to a VECTOR, there are two ways to create a UVECTOR: type it in, or use the SUBR 
UVECTOR. When typing in a UVECTOR be careful that everything you type in is of the same TYPE. 
before EVALuation, as well as after! 

<SET X 10>$ 
10 

<SET A 1[20 .X]>$ 

•ERROR* 

TYPES-DIFFER-IN-UNIFORM-VECTOR 

READ 

LISTENING-AT-LEVEL 2 PROCESS 1 

This error occurred because .Xisa FORM, even though itEVALstoa FIX. To do this properly, 

<SET A <UVECT0R 20 .X»$ 
I [20 10] 

A SUBR called UTYPE returns the name of the TYPE of the elements of a given UVECTOR. There are a 
few TYPEs which are illegal elements of UVECTORs: the only one you are likely to come across is 
STRING. 

UVECTORs are useful only for efficiency. They take up roughly half fhe storage of VECTORS. All 
other considerations are the same as for VECTORS. 



8.4. PRIMTYPE STRING 

A MDL STRING is a sequence of MDL objects of TYPE CHARACTER. Objects of TYPE CHARACTER 
are represented by the sequence of characters: exclamation-point, backslash, and the character 
itself. 
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WAS 

l\A 

<TYPE |\A>$ 

CHARACTER 

<ASCII |\A>$ 

66 

<ASCII 65>$ 

l\A 

8.4.1. ASCII 

8.4.2. Creating STRINGS 

ST* IKGs are cea.eC in exac,, y ,ne ^ ways „ „ 0(ner ^^ 

<SET A -THIS IS A STRIHG">$ 
"THIS IS A STRING" 

S- <STRING ,XT ,NH,vi us »* 

SB STRING * - — - - * * ~ can te either characters or wher 

<SET A "THIS IS A->$ 
"THIS IS A" 

<STRING .A - STRING">$ 
"THIS IS A STRING" 
■ A$ 

"THIS IS A" 
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<SET A "\"\"">S 

<LENGTH .A>$ 
2 

This STRING has two elements, each a double-quote. To put a backslash into a STRING, the 
backslash must be preceded by another backslash. This is even more confusing. 

<SET A "\\\' M, >$ 
•\\V" 

<LENGTH .A>$ 
2 

This is another STRING of two elements: a backslash and a double-quote. 



8.4.3. EVALing STRINGS 

STRINGS are unlike LISTs and VECTORS in that they evaluate to themselves, rather than to copies 
of themselves. 



8.4.4. Manipulating STRINGS 

STRINGS are manipulated exactly as are VECTORS. The CHARACTERS are stored sequentially; thus 
PUTREST will not work, but BACK and TOP will. The only difference is that the only legal third 
argument to PUT of a STRING is a CHARACTER. Anything else will cause an error. 

It is important to note that STRINGS contain only CHARACTERS. CHARACTERS with special meanings 
elsewhwere in MDL are simply CHARACTERS in STRINGS. 

<SET A "1 2 3 <+ 2 2>">$ 
"1 2 3 <+ 2 2>" 
<3 .A>$ 
2 

The above example shows that the 'FORM' in the STRING is not EVALed, it is merely 7 CHARACTERS in 
a STRING. Spaces are CHARACTERS. 

There is a major difference between the following two structures: 
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<SET L (-1 2 3" - 4 6 6" "7 8 g-)>$ 
("1 2 3" "4 6 6- -7 8 0") 
<SET S -(1 2 3) (4 5 6) (7 8 9)">$ 
"(* 2 3) (4 5 6) (7 8 9)- ' 

<LENGTH ,L>$ 



3 

<LENGTH .S>$ 
23 



8.5. Building Large Structures 



of 100 events by i^ft^ *™« * JJJ painful to create, say. a VECTOR 
mumm of a specific size, namely the «£ StS WF?™ " M ° L Pr ° VideS a way l0 creat * 
arguments, a FIX (the number of e emen.s) an/a MDl' SE^J? 1 ISTRIN6 ' These tak * two 
VECTOR, or STRING, respectively) with mS^Xt h h 5 ^ a ■*«" < LIST > 
second argument to the SUBR. Some examples WhlCh ' S ,he resu,t of bating the 

<ILIST 10 0>$ 

(0 00000000 0) 
<IVECT0R 6 <»$ 

sshm/ks ° #false ° ' false « «« cm 

"WWWWWWkWWwWWWWWWWWWWWWWWWWWWW- 

The second argument to ILIST and TUFrmo 

ISTRING must be . CHARACTER VECT ° R °" ta any MDL <***«• The second argument to 



8.6. Searching Structures 



C^SrXKJi^^ arbitrary s„ uc , u , e , will , ook 
wrth the struotare, they iook at the firs. SZSS ~ ?« . "' Wha ' ' hey do is «* darting 

hey return the *,„,«„„. otherwise they REST fhp <T 1"""' '° " le ° biecl in « uesli °"- » so 
.he s<,uc,u, e becomes EMPTY? ,i. e . , e ob ec, wa^n t n h' * ' T "P"" ,he Pr ° Cedure ' W ^' 
#FALSE ( ,. This means |na , a successful MEMO r M Mnp T"* W '" C ""* ) " ,hese SUB "s return 
down such that its firs, element is the ob^c, searched for ^ 0ri9 '' na ' S "" C "" e R «Ted 

smgte.equal(.?). y ' me tesl ,s double-equal (««?,, while in MEMBER the test is 
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<SET L (ONE 2 3.0 "F0UR")>$ 

(ONE .2 3.0 "FOUR") 

<MEMQ 2 .!_>$ 

(2 3.0 "FOUR") 

<MEMQ "FOUR" .L>$ 

#FALSE () 

<MEMBER "FOUR" .L>$ 

("FOUR") 



8.7. Garbage: Quoting Structures 

Often in writing programs, one includes a structure in a FORM. For example, one might have a FORM 
that looks like this: 

<NTH [ADD SUB MUL DIV] .0PCODE> 

This is very inefficient because the VECTOR in the FORM is EVALed every time the FORM is EVALed with 
the result that a new VECTOR is created. This creates a lot of 'garbage', where 'garbage' is defined as 
some piece of structure which is no longer used (i.e. there are no pointers to it). Since your MDL 
resides in a machine with finite memory, it pays to think about ways of making programs relatively 
storage-efficient. The proper way of writing the FORM in the previous example is 

<NTH '[ADD SUB MUL DIV] .0PC0DE> 

As mentioned earlier, the quote will ensure that the VECTOR will not be EVALed when the FORM is 
EVALed. Thus, only one copy of the VECTOR will exist. Note that 'quoting' structures in this way 
should be used for VECTORS and LISTs. STRINGS EVAL to themselves! You are warned: NEVER do a 
PUT into a quoted structural 



8.8. Garbage: Building Lists 

It is often necessary in a program to build up a LIST of elements. Assume that you have a 
FUNCTION which gets elements one at a time and wants to build a list in the order in which they were 
received. Assume a LIST L and an element to be added, say .OBJ. One way of doing this is as 
follows: 

<SET L (I.L .0BJ)> 
This is not good practice, as the LIST created is a copy of the old one with an element added at the 
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end. Assuming that nothing else but the value of L points to th* t r*T i * „ , ™ T 
become garbage. If you assume addinn inn JL P ° nis . t0 the LIST - L - *W old LIST .L will 
thousands of LIST element ^ n3Sly ^^r 9 "? ^^ * bSC ° meS dear lhat 
VECTOR. The best way of doing ^s^^ 

<SET L (1 2 3)>$ 
(1 2 3) 

<PUTREST <REST .L 2> (4)>$ 

(3 4) 

• L$ 

(12 3 4) 

Notice that in the genera, case, one can add an element to the end of a L 1ST by saying: 
<PUTREST <REST .LIST <- <LE«GTH .LIST> 1» (. ELEMEN T)> 

S fi£ "S?^^ *» * which are puite s.ow for 

elements. Here's another way of doing thT P °" lterS to ,he ** lo count U P «N 

<SET6 L (T)>$ 

(T) 

<SET6 LL ,L>$ 

(T) 

<DEFINE ADD-TO-END (ELEMENT) 

ADD-TO-END^ U **" <PUTRMT '" l-*""» »»>$ 

<ADD-TO-END tOO>$ 
(100) 

<ADD-T0-END 200>$ 

(200) 

.L$ 

(T 100 200) 

effect of the program ADD-TO-END bSlS.^ be EMPTY? ' by de ' ir "' lion - ™e 
.™e. This saves having ,o perfom, lon?KS J^l L " J LL) Wh '' Ch h " ESTed each 
being changed with every PUTREST Thus , I mEZZ , P , 111°°* ¥"** U ' S a SUb - |isl °' L ' L is 
lo its las, element. You should SLJKzSS!? £2 and LL is always L "ESTed down 
at a later time.... remember, of course, that the Initial T in the UST should be removed 
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8.9. Structured NEWTY PEs 

In the previous chapter, we saw that MDL is a type-extensible language in that the programmer can 
create his own TYPEs. Typically, an object of a NEWTYPE will be a structure that is a model of some 
real world entity with the elements of the structure models of parts or aspects of that entity. The 
creator of the NEWTYPE will usually provide functions for manipulating the NEWTYPE objects in all of 
the ways which are considered meaningful for the intended uses of that NEWTYPE. This means that 
other users of the NEWTYPE can use these creator-defined manipulation routines and never need to 
know the interna! structure of the NEWTYPE. This provides both modularity of programming and data 
abstraction. 

For example, suppose you wanted to deal with airline schedules. If you were to construct a set of 
programs that define and manipulate a NEWTYPE called FLIGHT, then you could make that set into a 
standard package of programs and call on it to handle all information pertaining to scheduled airline 
flights. Since all FLIGHTS would have the same quantity of information (more or less) and you would 
want quick access to individual elements, you would not want the TYPEPRIM to be LIST. Since the 
elements would be of various TYPEs, you would not want the TYPEPRIM to be UVECTOR. The natural 
choice would be a TYPEPRIM of VECTOR. 

Now, the individual elements of a FLIGHT would, no doubt, have TYPEs and meanings that don't 
change. The elements of a FLIGHT might be airline code, flight number, originating-airport code, list 
of intermediate stops, destination-airport code, type of aircraft, days of operation, etc. Each and 
every FLIGHT would have the airline code for its first element (say), the flight number for its second, 
and so on. It is natural to invent names (ATOMs) for these elements and always refer to the elements by 
name. For example, you could <SETG AIRLINE 1>. Then, if the local value of F were a FLIGHT. 
<AIRLINE .F> would return the airline code, and <AIRLINE ,F AA> would set the airline code to 
AA. Once that is done, you can forget about which element comes first; all you need to know are the 
names of the offsets. 

The next step is to notice that, outside the package of FLIGHT functions, no one needs to know 
whether AIRLINE is just an offset or in fact a function of some kind. For example, the scheduled 
duration of a flight might not be explicitly stored in a FLIGHT, just the scheduled times of departure 
and arrival. But, if the package had the proper DURATION function for calculating the duration, then 
the call <DURATI0N . F> could return the duration, no matter how it is found. In this way the internal 
details of the package are conveniently hidden from view and abstracted away. 



8.10. Summary of MDL Structures 

A few points should be obvious from the previous discussions of the various structured 
PRIMTYPEs: 

1.AII structures can be created in the same two ways: Either type in the printed 
representation, or use the SU8R whose name is the name of the PRIMTYPE. 

2. When LISTs and VECTORS are EVALed, a new copy of the structure is made, whose 
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UvIcTORs S and C ST rThgI)' ^ °" *" COnsecu "ve'y stored structures (i.e. VECTORS. 

6. The SUBR PUTREST works nn i tct . 

7. TheSUBRsHEMQandMEMRFP^ l 

«MQ uses =. ? Q as ? £?%£&£» *-' T 1? " 3 " ■—» —*• 
down ,o «h. MDL object which was found, or # F ALSE Q." ** "*>"* "»»" «W 



8.11. Practice Quiz 



Please write below each line the 



result of typing that line into a MDL. 
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9. Programming Constructs 



In order to write any interesting programs, an ability is required to test for various conditions and 
take action only if those conditions are met. This chapter introduces the MDL SUBRs and FSUBRs 
needed to do this. 



9.1 . Boolean Operators 



9.1.1. NOT 

The MDL predicate NOT takes one argument of any TYPE. It evaluates to T only if its argument 
evaluates to a FALSE, and to #FALSE ( ) otherwise. 

<NOT <L-? 4 3»$ 

T 



9.1.2. AND 

AND is an FSUBR. and it takes any number of arguments. It evaluates its arguments from first 
toward last as they appear In the FORM. As soon as one ol them evaluates to a FALSE, it returns that 
FALSE, ignoring any remaining arguments- If none of them evaluate to FALSE, it returns EVAL of its 
last argument. <AND> returns T, 

<AND <G? 4 3> <SET A 6> <L? 4 3> <SET B 7»$ 

#FALSE () 

.AS 

6 






;-.i c.ik i:j nn 
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•ERROR* 

UNBOUND VARIABLE 
B 

LVAL 

LISTENING AT LEVEL n PROCESS 1 

<AND <G? 4 3> <L? 3 4> <SET C 10»J 

-CS 
10 

A~0 7 „ lh . SUBR men> to AN0 m „ arflumenis are eua|uaied be(ore ^ ^ [hem s ^ 

9.1.3. OR 

non-FALSE va.ue. ignoring any remamfng ^men* Z!^ t0 " nonFALSE - OR returns that 
saw. <0R> returns #FALSE (). a arguments. If th.s never occurs, it returns the last FALSE it 

<0R <L? 4 3> <SET D 6> <SET E 13», 

Setting D to 6 returned 6, which is not a FA! *e *« i* 

is not a FALSE. so H was returned by OR and E was never set to 13 
OR? is the SUBR equivalent to OR. 

«2ZXXtt^ — no IroUbIe „,,„ MD , S boolean 

<N0T <0R .F00 .BAR .BLETCH» 
<AND <N0T .F00> < N0T .BAR> <N0T .BLETCH» 



9.2. COND 
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there must be at least one- COND always returns the result of the last evaluation it performs. The 
following rules determine the order of evaluations performed. 

1. Evaluate the first element of each clause (from first toward last) until either a non-FALSE 
object results or the clauses are exhausted. 

2. If a non- FALSE object is found in (1 ). immediately evaluate the remaining elements (if any) 
of that clause and ignore any remaining clauses. 

In other words. COND goes walking down its clauses, EVAUng the first element of each clause, looking 
for a non-FALSE result. As soon as it finds a non-FALSE. it forgets about all the other clauses and 
evaluates. In order, the other elements (if any) of the current clause and returns the last thing it 
evaluates. If it can't find a non-FALSE first element, it returns the last FALSE it saw. 



9.2.1 . Examples 






<SET F '(1)>S 

(i) 

<COND (<EMPTY? . F> 
EMP) 
(<1? <LENGTH 
ONE)>$ 
DUE 



F>> 



<SET F ()>S 

() 

<COND (<EMPTY? .F> 

EMP) 

(<1? <LENGTH 

ONE)>S 

EMP 



F» 



<SET F '(1 2 3)>S 

(1 2 3) 

<COND (<EMPTY? .F> 

EMP) 
(<i? <LENGTH -F» 

ONE)>$ 
#FALSE () 
<COND (<LENGTH? -F 2> 

SMALL) 
(BIG)>S 
BIG 
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<DEFINE FACT (N) : "the standard recursive factorial" 
<COND (<0? .N> 1) 

(ELSE <• .N <FACT <- .N 1>»)»$ 
r ACT • 

<FACT 6>J 

120 

In the last example, the use of ELSE was not necessary, but it makes it a bit easier to read the 
program. The atom T is often used for the same purpose. 



9.3. Shortcuts with Conditionals 



9.3.1 . Using AND and OR with CONDs 

rJSSL^ Tf °1 arS FSUflR f thSy C3n * USed "• ****>*• CONDs. but this is usually bad 
programming style. A construct of the form 

<AND pre-conditions action(s)> 



or 



will 



<0R pre-exciusions action(s)> 



allow acnonfs) to be evaluated only if all the pre-conditions are true or only if all the ore- 

rZ ^LTl ■ fCSpec,ivo '/ Bv ne *ting »"«« using both AND and OR. fairly powerful constructs 

^o^Tetu^n, f°X Ver ' , U 9 N ° and ° R '" ,hlS W3y C3n ' ead IO SOme maior P^b.ems. If any of your 
nr««« 1 UB unexpectedly, the following ones will never be evaluated. Even worse. 

anyone e7seTo7oHow ***" ° f d ° InS ** lMd ,0 ""* V ro * ra ™ ■*** «™ very difficult for 

cJE? «r nl a ^ i r, ,e ^ ded . , ° bS USed J: C ° ND C ' aUSeS - " yOU wanted to make «"• ,ha * « argument 
called ARG passed to a function was a FIX between 6 and 10 inclusively: 
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<COND (<ANO <--? <TYPE .ARG> FIX> 
<G = ? .ARG 6> 
<L-? -ARG 10» 
<what you want to do>) 
(ELSE <wftaf you want to do otherwise>)> 

It. instead, you wanted to make sure the argument was a FIX pytgide that range: 

<COND (<AND <«? <TYPE -ARG> FIX> 
<0R <G? -ARG 10> 
<L? .ARG 6>» 
<what you want to do>) 
(ELSE <whaf you want to do otherwise>)> 

9.3.2. Embedded Unconditionals 

One of the disadvantages of COND is that there is no straight forward way to do things 
unconditionally in between tests. One way around this problem Is to insert a dummy clause that never 
succeeds, because its only element is an AND that returns a FALSE (or the test (this method is strongly 
discouraged). Example: 

<COND (<0? -N> <F0 .M>) 
(<1? .N> <F1 .N>) 
(<AND <SET N <• 2 <FIX </ -N Z»» 

:"Round .N down to evan number." 

<») 

(<LENGTH? .VEC .N> '[]) 
(T <REST .VEC <+ 1 -N»)> 

The preferred method is to increase the nesting with a new COND after the unconditional part. This 
method does not make the code appear to a human reader as though it does something other than 
what it really does. The above example should be done this way: 

<COND (<0? .N> <F0 .N>) 
(<1? .N> <F1 .N>) 

(T 

<SET N <• 2 <FIX </ .N 2»» 
<COND (<LENGTH? .VEC -N> '[]) 

(T <REST .VEC <+ 1 .N»)>)> 



section 9.3 f noon amming cons rnuurs 



74 

THE MDL PRIMER 

9.4. Examples 

The following program will print all the prime factors of a given number: 

<DEFINE FACTOR (N) 

<FACTOR-FROM .N 2>> 

<OEFINE FACTOR-FROM (N TEST-DIVISOR) 

<COND «G? <• .TEST-DIVISOR . TEST-DIVISOR> . N> 
<CRLF> 
N) 
(<0? <MOD .N .TEST-DIVISOR» 
<PRINT .TEST-DIVISOR> 

<FACTOR-FROM </ .N . TEST-DIVISOR> 
•TEST-DIVISOR>) 
(ELSE <FACTOR-FR0M .N <+ .TEST-DIVISOR 1»)» 

-•KSbS^^ ! ? ddI ° "- — «"« with it. vou 

tested). Why does *. proJr^^Sn^^^ ZllZ ctT^Z^^ ^ * ^ ^ 
tests only with prime numbers? 'actors? Can you improve the program so that it 

One way to write a test for prime numbers would be: 

<DEFINE PRIME? (X) 

<--? -X <FACTOR .X>»$ 

^X^^^x^^^^x ,o 2* a new vers,on °* factor ■* ■* *** 

y 9 vvouia tms test for prime numbers improve FACTOR-FROM? Why not? 
heard to say that Zork is a huge coScSSonTl) * ° '** imp,e ' nenlor s of Zork has been 
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<DEFINE RUSTY-KNIFE-FUNCTION () 
<COND (<--? .VERB TAKE> 

<COND (<IN? .SWORD .PLAYER> 
<PRINC 
"As you pick up the rusty knife, your sword gives a single 
pulse of blinding blue light. "> 

<CRLF>)> 

' <>) 

(<OR <AND <"? .INDIRECT-OBJECT . RUSTY-KNIFE> 

<MEMQ .VERB '[ATTACK KILL]» 
<AND <MEMQ .VERB '[SWING THROW]> 

<"? .OIRECT-OBJECT ,RUSTY-KNIFE> 
. INDIRECT-OBJECT» 
<REMOVE .RUSTY-KNIFE> 
<JIGS-UP 
"As the knife approaches Its victim, your mind 1s submerged by 
an overmastering will. Slowly, your hand turns, until the 
rusty blade 1s an Inch from your neck. The knife seems to sing 
as 1t savagely slits your throat. ">)» 

This function is called whenever "the rusty knife" is referred to in any way- This function checks 
whether the verb is "take" and the player has the "sword." If so the first message is printed and 
#FALSE () is returned. If the verb was not "take", it checks whether either the Indirect object is 
"rusty knife" aod the verb is "attack" or "kill", fi£ the verb is "swing" or "throw" and the direct object 
is "rusty knife" && there is an Indirect object. If so. the "rusty knife" is removed from the game, an 
interesting message is printed, and the player dies. 
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10. Looping 



One of MDL's strongest points is its variety o! powerful looping constructs. These will be covered 
in this chapter. 



10. 1. PROG 

PROG makes it possible to encapsulate sections of MDL code. A PROG is very much like a 
FUNCTION in syntax. It takes a LIST which is similar in some respects to an argument list, and an 
arbitrary number of MDL objects which are EVALuated in turn. It returns the result of the EVALuation 
of the last object in its body. Here is a prosaic PROG: 

<PR0G () <SETG A <» <SETG B <» <INITIALIZE» 

Notice that each of the three FORMs in the PROG could have been done without using a PROG. PROGs. 
however, are a bit more useful than this would indicate. 

First, the LIST can contain any number of 

-ATOMS 

- LISTs containing an ATOM and an arbitrary initial value for that ATOM. 

All of these ATOMs will be re-bound inside the PROG (i.e. as if a new FUNCTION were entered.) When 
the PROG returns, the ATOMs will be unbound (i.e. re-bound to their old values, if any.) Thus, a PROG 
can be thought of as a mini- FUNCTION of no arguments. 



<PR0G (A B (C 10) (D .F00)) > 

In this example, four new bindings are made. The ATOMs A and B are bound, but not assigned a value. 
The ATOM C is bound to 10 and the ATOM D is bound to the current LVAL of the ATOM F00. ATOMs 
should be placed in this 'argument' LIST when they are used as temporary variables inside the PROG. 
A full explanation of the use of temporary variables is in section ^ 1 .5. 

More importantly, a PROG can be restarted or caused to return from the middle any lime using the 
SUBttu AGAIN and RETURN. At this point. It is sufficient to say Hint AGAIN with no arguments starts 
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a,wa ys re ,er ,o fta nearest ^"^t S !£££ ""* RETU " N " ^"'^ - 
JoToX^T ^ ' air,y US6leSS * "*. but .he FSUB* REPEAT. which „ very ^^ „ 



10. 2. REPEAT 

te done. There ,s no Cher way £ ISSSw JSSK wSSff"*' ^"'^ " -l ' """"" 

<REPEAT ((CNT 6)) 

#DECL ((CNT) FIX) 

<C0N0 f?i£J c c^„r *» °> «- *» 

4 
3 
2 
1 
T 



10.3. Non-local RETURNS, etc. 

™^1£^ B«5S «*» • <° --place other than the nearest 

PROG. REPEAT, or FUNCTION by P^^^^^n^^^ a " OWS *°" lo »«*»■ any 
argument list or PROG/REPEAT lis!. This has the Pltar? «?l- ' " 0wad by an AT0M at «he and of an 
ACTIVATION which becomes a legal ad3tto?il «rn . u 9 ' ha ' AT0M IO an ob ' ect °' TYPE 

can take an optional MTtMMio^t^^^^, * ^ AGA ™ and RETURN ™«* AGAIN 

and RETURN takes a return value and an optional ACTIVATION. 

The most common use of Return /«r.ir*i . .„ «- 
you have a FUNCTION eoo"^ H ^ A ^"!^^ w ^ is in e "" ^nd.ing. Assume that 
notices something wrong. BLETClTnlh. wan! £ , 2225 CS " S a FUNCT TON BLETCH which 

example, or print an erro? message Site is nnlJ L h ^ ? HCTI0N F0 ° to return a FALSE, for 
'named activation', whose 'namj ^kno^n % Tu^ToN BLETCH CTI °" F °° * ^"^ '° »*" a 



LOOPING 

SECTION 10 1 



r 



THE MDL PRIMER 



79 



<DEFINE FOO (A) 

<COND (<PR06 ("NAME" ACT) <BAR -A» 
<PRINT .A> T) 
(T <PRINT "ERROR IN YOUR PROGRAMS T)»$ 
FOO 
<DEFINE BAR (X) 

<BLETCH <• .X .X>»$ 
BAR 
<DEFINE BLETCH (Z) 

<COND (<G? -Z 10> <RETURN #FALSE () .ACT>) 
(T <SQRT .Z>)»$ 
BLETCH 
<FOO 2>t 
2 T 

<FOO 4>$ 
"ERROR IN YOUR PROGRAM" T 



10.4. MAPF 



10.4.1 . Looping Through a Structure 



MAPF (pronounced 'map-elf lor 'map-Ilrst') is mainly used to apply a function to each element ol a 
structure, in turn. In this most simple iorm. its first argument is a FALSE, its second argument a loop- 
function, and its third argument a structure. Here is a simple MAPF: 

<MAPF <> 

<FUNCTX0N (X) 

<PRINT .X» 

(12 3 4)>$ 
1 
2 
3 
4 4 

The lost 4 is the result ol the MAPF (the result ol the last application ol the loop-function to an element 
of the structure. 

An FSUBR called FUNCTION is used in many places in this chapter. FUNCTION is very much like 
DEFINE, except that no name is specified. FUNCTIONS created with FUNCTION are said to be 
■anonymous". They cannot be used oulside the FORM in which they aro imbedded, since they have no 
name by which they can be referenced. Of course, if tho loop function you wish to use had already 
beon DEFINEd. you would lelor toltin a MAPF as the global value of its name. 
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<DEFINE FOO (A B) <+ .A .B»$ 

F00 

. FOOS 

♦FUNCTION ((A B) <+ . A .B>) 
<FUNCTION (A B) <+ .A .B»J 
•FUNCTION ((A B) <+ .A .B>) 



-=^^^s^ 






<DEFINE BAR (L) 
<MAPF <> 

<FUNCTION (X) 

<COND (<G? .X 10> <MAPLEAVE FOO) 
(T <PRINT .X>)» 
.L»J 
BAR 

<BAR (12 3 4)>J 

1 

2 

3 

4 4 

<BAR (1 2 16 7 6 2)>J 

2 FOO 



10.4.2. OtherThan One Structure 

structures becomes EMPTY? structures. The NAPF will stop when any of the 



<MAPF <> 

<FUNCTI0N (A B C) 

<PRINT <+ .A .B .C>» 
(13 6 7) 
(2 4 6 8) 
(3 6 7 9)>$ 

12 

IB 
24 24 
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<MAPF <> 

<FUNCTION (A B C) 

<PRINT <+ -A .8 -C>» 
(1 3 B) 
(2 4 6) 
(3)>$ 
8 6 

'Other Than One' also includes zero, but this is a special case. A HAPF with only two arguments is 
something like a REPEAT loop. It can only be terminated by an explicit call to MAPLEAVE. See section 
10.5. II any of the structures is empty to begin with. MAPF returns #FALSE (). 



10.4.3. Using Intermediate Results 

By now you must be wondering why there is a FALSE as the first argument to MAPF. In fact, a 
FALSE tolls MDL not to do anything with the results of applying the loop-function to the elements of 
the structure. However, if the first argument to MAPF is something which can be applied to arguments 
(I.e. a FUNCTION or SUBR), then MDL will 'save* the results of applying the loop-lunction and. when 
the looping is finished, apply the first argument (called the final-function) to all ol the 'saved' results. 
An example: 



<MAPF 



(2 4 



<MAPF 



12 



.LIST 
{FUNCTION (X Y) 

<+ .X <SQRT -Y>» 



(12 3) 




(1 4 9)>S 




6) 




.+ 




{FUNCTION (X Y) 




<+ .X <SQRT 


.Y»> 


(1 2 3) 




(1 4 9)>$ 





In ihe first case, we built a LIST out of the results of the loop-function. In the second, we simply 
added up all of the results. 



10.4.4. MAPRET and MAPSTOP 

There are cases In which you might want to have an arbitrary number of resulls 'saved*. This can 
be done with ihe SUDR MAPKET which lakes any numbor of argnmenls (includinrj zero), causes the 
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function to terminate, and 'saves' all of its arguments. 

<DEFINE PRIME-LIST (L) 

<MAPF .LIST 

<FUNCTION (NUN) 

<CONO (<PRIME? .NUM> .NUM) 

(T <HAPRET>)» 
,L»$ 

PRIME-LIST 

<PRIME-LIST (2 4 11 66 73)>$ 
(2 11 73) 

function. MAPRET. o, course. win nT^Tj* S ZSSS^^SSST * °" 
Assuming the function PRIME? described in chapter*) has been written: 

<DEFINE PRIME-AND-SQUARES-LIST (L) 
<HAPF .LIST 

<FUNCTION (NUM) 

<COND (<PRIME? .NUM> <MAPRET .NUM <• .NUM .NUM») 
(T <MAPRET>)» ' 

.L»S 

PRIME-AND-SQUARES-LIST 

<PRIME-AND-SQUARES-LIST (2 4 11 66)>S 
(2 4 11 121) ' 

A more useful function: 

<DEFINE UPPERCASIFY-1 (STR) 

<MAPF .STRING 

<FUNCTION (CHAR) 

<SET ASC <ASCII .CHAR» 

<CONO (<AND <G-? .ASC <ASCII I \a» 

<L-7 .ASC <ASCII l\z>» 

<MAPRET <ASCII <- .ASC 32>») 

(ELSE <MAPRET .CHAR>)» 
.STR»$ ' 

UPPERCASIFY 



S5^S£73J!m t,m9 for fll1 fl0 ° d raen to <F0 ° - BAR >"> 

"NOW IS THE TIME FOR ALL GOOD MEN TO <FOO .BAR>- 
. t - 5 fr* 

"Now 1s the time for all good men to <F00 .BAR>" 
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The SU8R MAPSTOP is Ihe same as MAPRET, except that, after 'saving' its arguments, it finishes the 
MAPF. allowing the final-function to be applied to all of the 'saved' results. Like MAPRET, MAPSTOP can 
only be used if there is a final-function. 



10- 4. 5. MAPR 

■ 

The SUBR MAPR (for 'map-rest.' pronounced 'mapar') is exactly like MAPF in every respect except 
that the arguments passed to the loop-function, rather than being successive elements of the 
structures, are the structures themselves RESTed down successively. The names for the two map 
SUBRs are mnemonic: MAP First and MAPRest. 

<MAPR <> 

<FUNCTION (X) 

<PRINT .X» 

(12 3 4)>S 
(12 3 4) 
(2 3 4) 
(3 4) 
<4) (*) 

MAPR is useful if it is necessary to change elements ol the structure(s) that you are mapping down. 
Here is a FUNCTION which takes a structure full of numbers and changes it to contain double the old 
values: 

<DEFINE DOUBLE (STR) 
<MAPR <> 

<FUNCTION (S) 

<PUT .S 1 <• <1 -S> 2>» 
.STR»$ 
DOUBLE 
<SET L (1 2 3)>S 

(1 Z 3) 

<DOUBLE .L>S 

(6) 
-L$ 
(Z 4 6) 

In UPPERCASIFY-1 a MAPF was used which generated a new structure. Using MAPR. a new 
function can be written which modifies the original string: 
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<DEFINE UPPERCASIFY-2 (STR) 
<MAPR O 

<FUNCTION (STR1) 

<SET ASC <ASCII <1 .STR1»> 
<COND «AND <G-? .ASC <ASCII l\a» 
<L-? .ASC <ASCII !\z>» 

<PUT .STR1 1 <ASCII <- .ASC 32»>)» 
. STR** 
.STR>$ 
UPPERCASIFY-2 

<UPPERCASIFY-2 <SET STR "Mow Is th. t1*« for <BAR .BLETCH>"»J 
"NOW IS THE TIME FOR <BAR ,BLETCH>" 
-STRJ 

"NOW IS THE TIME FOR <BAR .BLETCH>" 
us"* This hSSX^ "2 Chan9e *" e *' Stin9 slruclure - Th ° following example shows another 

<DEFINE UNIQUIFY (STRUC) 

<COND (<NOT <STRUCTURED? .STRUC» 

0FALSE ( "WRONG TYPE OF ARGUMENT")) 
(ELSE ' 

<CHTYPE 
<MAPR ,<PRIMTYPE .STRUO 
<FUNCTION (S) 

<COND (<MEMQ <1 . S> <REST .S» 
<MAPRET>) 

(ELSE <MAPRET <1 .S»)» 
.STRUO 
<TYPE .STRUC»)»$ 
UNIQUIFY 

<UNIQUIFY #FROB (1 2 33 2 l 6 )>J 
#FR08 (33 2 16) 

If you wished to be able to ^ove elements which "look the same." such as structures which are -7 
MEMBER. whfcnrssJwV 2 3) " ° r FR ° TZ ^ """^ VOU WOU ' d haue <° -P' a - "ha MEMO with 



10.4.6. MAPF/R Summary 

The syntax for MAPF/R is as follows: 
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<MAPF/R final-function 
loop-function 
siructure-1 

structure-ny 
with only the first two arguments required. 

10. 5. Looping vs. Recursion 

In the previous chapter, the "standard recursive factorial" was shown. It can now be rewritten 
using the looping constructs introduced in this chapter. 

<DEFINE FACT (N) 

<REPEAT ((ANS 1)) 

<COND (<0? .H> <RETURN .ANS>) 

(ELSE <SET ANS <• .ANS .N» 
<SET N <- .N !»)>» 

Some might argue that this is a larger and more complicated program to write than the recursive form, 
and therefore inferior. The iterative form just shown, however, is faster and more efficient. 

The same program can also be written using MAPF. 

<DEFZNE FACT (N) 

<SET ANS 1> 
<MAPF <> 

<FUNCTION () 

<COND (<0? .N> <MAPLEAVE .ANS>) 

(ELSE <SET ANS <• .ANS .N>> 
<SET N <- .N 1>>)»» 

Or. more elegantly: 

<DEFINE FACT (N) 
<MAPF , • 

<FUNCTION () 

<COND (<07 .N> <MAPSTOP>) 

(ELSE <+ 1 <SET N <- .N 1»>)>»> 
; "<FACT 0> will return 1 since • of no arguments 
returns 1." 
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11. Argument Lists in FUNCTIONS 



In Chapter 6, the creation of a simple type of FUNCTION was explained: a FUNCTION taking a fixed 
number of arguments all of which get EVALed. While this may be sufficient for writing most of your 
FUNCTIONS, there are other ways in which you might like arguments to be handled. Some ol these 
might include: 

FUNCTIONS which can take an arbitrary number of arguments (like the SUBRs +, -. LIST. 
VECTOR, etc.) 

FUNCTIONS which act more like FSUBRs (i.e. they don't have their arguments EVA Led ) 

- FUNCTIONS which can take optional arguments, which can be defaulted. 

In fact, all of these things (and a few more) can be done easily by specifying them in the argument list 
of the FUNCTION. The remainder of this chapter will describe the complete syntax for MOL argument 

lists. 



11.1. Arguments Not EVA Led 

Placing a single-quote before an ATOM in the argument list will cause that ATOM to be given the 
value of its respective argument without EVALuation. 

<DEFINE F00 ('ITEM) . ITEM>$ 

F00 

<F00 <+ 1 2»$ 

<+ 1 2> 

Were the ATOM ITEM not quoted in the argument list, the FUNCTION would have returned the FIX 3. 
Quoting arguments, as It turns out. is not used often in MDL. 
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1 1 .2. Optional Arguments 

MDL can be lold to expect optional arguments by placing the STRING "OPTIONAL" in the 
argument list afier all of the required arguments. Following the STRING can be any number of ATOMs, 
which will be bound to the values of the optional arguments, if given. To specify that an optional 
argument is to have a default value (i.e. if not passed as an argument), place a LIST containing the 
ATOM and the default value in place of just the ATOM. Here's an example: 

<OEFINE ADO-ONE (NUM "OPTIONAL" (HOW-MANY 1)) 

<+ -NUM .HOW-MANY»$ 
ADD-ONE 
<ADD-ONE 10>S 
11 

<ADD-ONE 10 2>S 
12 

This rather useless FUNCTION adds the LVAL of HOW-MANY to its first argument. HOW-MANY is an 
optional argument, whose default value is the FIX 1- Therefore, with one argument. ADD-ONE adds 
one to its argument. With two arguments, it adds thern- 

As was mentioned earlier, it isn't necessary to supply a default value for an optional argument- If 
there is no default value, and the optional argument is not supplied, the ATOM gets bound, but is not 
assigned a value. LVAL of that ATOM will generate an error, because an ATOM must be both bound 
and assigned to have a local value. One can tell whether an ATOM has been assigned a value by using 
the SUBR ASSIGNED?, which returns T if its argument (an ATOM) is assigned; otherwise 0FALSE (). 
The following definition of ADD-ONE acts identically to the previous one: 

<DEFINE ADD-ONE (NUM "OPTIONAL" HOW-MANY) 

<COND (<N0T <ASSIGNED? HOW-MANY» 
<SET HOW-MANY !>)> 

<+ .NUM .H0W-MANY»$ 
ADD-ONE 

The use of single-quoted ATOMs is allowed with optional arguments as well as required ones- You 
may supply your own example, if you can think of one. We can't 



1 1 .3. Arbitrary Numbers of EVALed Arguments 

At any place in the argument list, after any required and optional (if any) argument:;, you can 
specify that all of the remaining arguments (supplied at the time of call) be EVALed and grouped 
togelher In a spucial structure called a TUPLE (for all practical purposes. TUPLEs may be thought of 
as VECTORS, and can be manipulated in the same ways). To do this, place the STRING 
"TUPLE" followed by an ATOM In the argument list. The ATOM will be bound to the TUPLE, Mere are 
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some examples: 

<DEFINE MY+ ("TUPLE" NUMBERS) <+ !.NUMBERS»$ 

MY+ 

<MY+ 12 3 4 6 6>$ 

21 

<MY+>$ 



<OEFINE MY-STRING ("TUPLE" STRINGS) <STRING I.STRINGS»$ 

MY-STRING 

<MY-STRING "THIS" "IS" "A" "BIG" "STRING" l\l>S 

"THISISABIGSTRING!" 

<DEFINE TIMES-PLUS ( NUM "TUPLE" NUMBERS) 

<• .NUM <+ I.NUMBERS>»S 
TIMES-PLUS 

<TIMES-PLUS 4 12 3>$ 
24 



1 1.4. Arbitrary Numbers of un-EVALed Arguments 

Instead of using "TUPLE", one could have used the STRING "ARCS". This has the effect of 
binding the following ATOM to a LIST of all of the remaining arguments. unEVALuafed. In fact, the 
ATOM is bound to the LIST which is the FORM used to call the FUNCTION RESTed down to the 
remaining arguments. The use of " ARGS " allows one to write FSUBRs in MOL. 

<DEFINE F00 ("ARGS" L) .L>$ 

F00 

<SET F '<F00 1 2 3»$ 

<FOO 1 2 3> 

<SET LL <EVAL .F»S 

(1 2 3) 

<--? .LL <REST .F 1»S 

T 

In the previous example, we explicitly called the SUBR EVAL. which caused EVALuation of the FORM 
<F00 1 2 3>. This returned the LIST (1 2 3). which is -•? to <REST -F 1>. 

Now we will write a FUNCTION to simulate the FSUBR DEFINE in MDL: this Is just what MDL does 
internally when the FSUBR DEFINE is called. 
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<DEFINE MY-DEFINE (NAM "ARGS" L) 

<SETG .NAM <CHTYPE .L FUNCTI0N» 
.NAM>$ 
MY-OEFXNE 

<MY-OEFINE FOO (A B C) <+ .A .B ,C»$ 

FOO 

.F00$ 

^FUNCTION ((A B C) <+ .A .B .C>) 
<F00 1 2 3>« 



Now (hat we have simulated OE FINE, let's try our hand at AND. 
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<DEFINE MY-AND ("ARGS" L) 
<REPEAT ((LAST T)) 

<COND (<EMPTY? .L> <RETURN .LAST>) 

(<NOT <SET LAST <EVAL <1 . L»» 
<RETURN -LAST>) 

(T <SET L <REST . L»)»>$ 

MY-AND ' 

bec^se ANO^nnTrn 816 "i" ^T" °' ^ ^ REPEAT ' ° P ***&** th * AT °" ^AST to T. 

L has Kcol EMPTY? "71 £ tuT '° re ' Urn T " THe '°° P itSe " nrSt cheCks on whetn * r »,• LIST 
to EVAL^?<? 1 > I tl? ' ' e F J r "f success ' ul - ™* LAST is returned. Otherwise. LAST is SET 
rer^ed El " ' S re,urnecI - Otherwise. L is RESTed once and the Poop is 

cal^ol" SSt COND.^atch 2t* " "' S ' e9ilimate " "" C ° N ° * *"* C ° N ° *"~. ** ■ *» 



1 1 .5. Temporary Variables 
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<DEFINE SUM ("TUPLE" NUMS "AUX" (SUM 0)) 
<REPEAT () 

<COND (<EMPTY? .NUMS> <RETURN . SUM> ) 
(T 
<SET SUM <+ .SUM <1 .NUMS>» 
<SET NUMS <REST .NUMS»)>»$ 
SUM 

<SUM 12 3 4>S 
10 

The FUNCTION SUM, in this example, simulates the SUBR +. The ATOM SUM is initialized to zero in 
the argument list. The following is identical in effect, although poor in style: 

<DEFINE SUM ("TUPLE" NUMS "AUX" SUM) 
<SET SUM 0> 
<REPEAT ...» 

It should be noted that the part of the argument list which follows "EXTRA" or "AUX" is identical in 
syntax and meaning to the 'argument list' which is the first argument to PROG and REPEAT. 



1 1 .6. Order of Evaluation in Argument Lists 

Unlike many other languages, including LISP. ATOMic bindings alter the required arguments are 
done from left to right, rather than simultaneously. This means that, (or example, the default values 
for optional arguments and extra variables can refer to the values of other ATOMs to their left in the 
argument list. 

<DEFINE FOO (A "OPTIONAL" (B <+ .A 10>) "AUX" (C <F00BAR -B>)) 
> 

The previous example shows an example of what is possible in argument lists due to MDL's order of 
evaluation. 



1 1 .7. Variable Declarations 

MDL has a built-in facility for checking the TYPEs of arguments to FUNCTIONS as well 33 other 
temporary variables. This is analogous to the checking which is done when F/SUBfls are called: if 
you call ihe SUBR + with an ATOM, for example, MDL will generate an error. In MDL. variables can be 
declared to be of a certain TYPE or group of TYPEs. This in done by placing an object of TYPE 
DECL (PRIMTYPE LIST) Immediately alter the FUNCTIONS argument hst. It may also follow the 
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argument list of a PROG or REPEAT and declare the variables bound within. The DECL (for 
"declaration," pronounced 'deckle') has the form of repeating pairs of LISTs of ATOMs (Ihe ATOMs to 
be declared) and the declaration proper. The simplest TYPE declaration is the name of a TYPE or the 
ATOM ANY. . 

0DECL ((FOO BAR) FIX (BLETCH) ATOM (MUMBLE) ANY) 

This declares the ATOMs FOO and BAR to be FXXes. the ATOM BLETCH to be an ATOM, and the ATOM 
MUMBLE to be anything. 

Another declaration form is the union of different TYPEs, which is specified by a FORM whose first 
element is the ATOM OR and the remainder legal TYPE names. 

*DECL ((NUM) <0R FIX FLOAT> (STRUC) <0R LIST VECTOR>) 

Also useful is the form <PRIMTYPE name-of-a-PRIMTYPE>, which specifies anything of that 
PRIMTYPE. For example: 

#DECL ((PL) <PRIMTYPE LIST>) 

will allow PL to be a LIST, a FORM, a SEGMENT, or any other PRIMTYPE LIST. 

In fact, the fullblown MDL declaration syntax is far more baroque than has been described, but 
these simple forms will suffice In almost all cases. For more information on DECL. consult The MDL 
Programming Language [Galley 79). Here are some examples of old friends, now including DECLs. 

<DEFINE MY-AND ("ARGS" L) 
#DECL ((L) LIST) 
<REPEAT ((LAST T)) 

#DECL ((LAST) ANY) 

<COND (<EMPTY7 .L> <RETURN .LAST>) 

(<NOT <SET LAST <EVAL <1 .L»» 

<RETURN .LAST>) 
(T <SET L <REST .L»)>»$ 
MY-AND 
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<DEFINE ADD-ONE (NUM "OPTIONAL" (HOW-MANY 1)) 

#DECL ((NUM) <OR FIX FLOAT> (HOW-MANY) FIX) 
<+ .NUM .HOW-MANY»S 

ADD-ONE 

<ADO-ONE 2.3 1.2>S 



•ERROR* 
TYPE-HISMATCH 



HOW-MANY 
FIX 
1.2 
EVAL 



"The ATOM of Incorrect TYPE" 

"The DECL fop that ATOM" 

"What the ATOM was about to be SET to" 

"EVALIng the FORM <ADD-ONE 2.3 1.2> caused 1t H 



LISTENIN6-AT-LEVEL 2 PROCESS 1 

Declarations have a number of purposes. First, they make your code easier for someone else to 
understand, as the sorts of arguments your FUNCTIONS take can be deduced from them. It will also 
help you read your own code at a later time when you may have forgotten how it all works. Second, it 
helps in debugging your programs, since an error will be caused if the declaration is violated. Finally, 
when your FUNCTIONS eventually get compiled, much better code can be produced with the 
information given by your declarations. Always DECL your FUNCTIONsl 



11.8. Structures: DECLs and NEWTYPEs 

Before closing our discussion of DECLs, one special type of declaration should be considered: that 
of structures. The syntax for this declaration is: 

<type-name <PRIMTYPE typeprlm> 

declaratlon-for-first-elemerit 
declaratlon-for-second-element 

• . • 
dectaration-tor-tast-oloment> 

For example, we could DECL a VECTOR of three elements as follows: 

<VECTOR FIX LIST <VECTOR ATOM ATOM» 

This declares the VECTOR to have a FIX. a LIST, and a VECTOR which must contain two ATOMS- 
There may bo more elements in a structure than those DECLed. Any additional elements will be 
considered to have the DECL ANY. 

<<PRIMTYPE LIST> ATOM <0R FIX FLOAT» 
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This declares a structure of PRIMTYPE LIST containing an ATOM and either a FIX or a FLOAT. 

We originally described the SUBR NEWTYPE as taking two arguments: the new TYPE name and its 
TYPEPRIM. Structured NEWTYPEs can take a third argument as well: a declaration, as described 
above. Let's use the airline problem from our earlier discussion. We will define a FLIGHT as follows: 

<NEWTYPE FLIGHT 

VECTOR 

•«PRIMTYPE VECTOR> ATOM FIX FIX»J 
FLIGHT 

<SETG AIRLINE 1>$ 
1 

<SETG FLIGHT-NUMBER 2>$ 
2 

<SETG DURATION 3>J 
3 

Notice that the declaration of FLIGHT is quoted: this is because it is a FORM and NEWTYPE is a SUBR. 
Now that FLIGHT is a legal TYPE. It can be used in declarations. In fact, it is a lot easier to say 

#DECL ((FL) FLIGHT) 

than to say 

#DECL ((FL) <VECTOR ATOM FIX FIX>) 

especially when you add another ten elements to the definition of FLIGHTS. It is also a lot clearer for 
both yourself and others to read. 



11.8.1. To NEWTYPE or Not To NEWTYPE 

That is the question most frequently asked. Should I make my table of house members a NEWTYPE? 
Should it just be a VECTOR? Sad to tell, there is no cut and dried answer. In general, whenever a 
structure has a 'significant' amount of internal structure, or some readily understood 'outside world 
meaning", it is a good idea to make it a NEWTYPE. Most people would deem a structure to have 
'significant' internal structure at the point when they type out the whole darn DECL tor the ninety- 
fourth time. Others think ahead. 
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1 1 .9. Good Habits / Bad Habits 

This chapter has some suggestions for good programming practice. You may ignore them at your 
risk, but we have found that people learning MDL are always more successful if they develop good 
habits early on in their MDLing. Here are the good habits: 

- Always use "AUX" to bind temporary variables in your functions. Don't use "free 
variables"! 

- A /ways DECL your FUNCTIONS. PROGs. and REPEATS. Even i! a variable can have any 
value, it Is good practice to DECL it as such, so that it is clear that you haven't simply 
forgotten. 



1 1 .10. Review of Argument List Syntax 

Here is a full-blown, ultra-hairy, and incredibly strange argument list: 

<OEFINE HAIR (A *B "OPTIONAL" (C 10) D 

"TUPLE" NUMS 
"AUX- (E <+ -A .B>) 

(F <SQRT </ .E .C») 
"NAME" F00) 
#DECL C(B C E) FIX 

(A E) <0R FIX FL0AT> 
(F 0) FLOAT 
(NUMS) TUPLE 
(F00) ACTIVATION) 
<C0ND (<N0T < ASSIGNED? 0» 
<SET <ATAN .B»)> 
<+ -A .B .C -D .E .F !.NUMS»$ 
HAIR 

This poor excuse for a FUNCTION takes two required arguments, the second of which is 
unEVALuatfcd, tv/o optional arguments, one of which defaults to 10, and any number of other 
arguments, bunched together in a TUPLE called NUMS- Two temporary variables E and F are also 
used, both of which refer to the LVALs of other ATOMs to their left in the argument list. 
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12.2. Conversion I/O - Input 



All of the following input Subroutines, when directed at a terminal, hang until $ (ESC) is typed and 
allow normal use of rubout, to, *■(_ and *8. 



12.2.1. READ 

<READ> 

This returns the entire MDL object whose character representation is next in the input stream- 
Successive <READ>s return successive objects. This is precisely the SUBR READ mentioned in 
chapter 3 (page 15). 



12.2.2. READCHR 

<READCHR> 

("read character") returns the next CHARACTER in the input stream. Successive <REAOCHR>s 
return successive CHARACTERS. 

12.2.2.1. NEXTCHR 

<NEXTCHR> 

n?, e ?«^ a ? C,er " ) reUjrns lhe CHARACTER which READCHR will return the next time READCHR is 
called (if READCHR is the next input SUBR called. Multiple <NEXTCHR>s. with no input operations 
between them, all return the same thing. 



12.3. Conversion I/O - Output 

If an object to be output requires (or can tolerate) separators within it (for example, between the 
?i?« J" a Struc,ured obiec! or a,,er ,he T YPE name in ■■# notation"), ihese conversion-output 

SUBRs will use a carnage-return/Hne feed separator to prevent overflowing a line. Overflow is 
delected in advance from elements of the CHANNEL in use. 
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12.3.1. PRINT 

<PRINT any> 

This outputs, in order, 

1 , a carriage-return line-feed, 

2. the character representation of EVAL of its argument (PRINT is a SU8R). and 

3- a space 

and then returns EVAL of its argument. This is precisely the SUBR PRINT mentioned in chapter 3 
(page IS). 

12.3.2. PRIN1 

<PRIN1 any> 
outputs just the character representation of. and returns, EVAL of any. 

12.3.3. PRINC 

<PRINC any> 

("print characters") acts exactly like PRIN1, except that 

1 . if its argument is a STRING or a CHARACTER, it suppresses the surrounding "s or initial I \ 
respectively; or, 

2. rf its argument is an ATOM, it suppresses any \s or OBLIST trailers which would otherwise 
be necessary. 

If PRINC's argument is a structure containing STRINGS. CHARACTERS, or ATOHs. the services 
mentioned will be done for all of them. Ditto for the ATOM used to name the TYPE in "# notation". 

12.3.4. CRLF 

<CRLF> 
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("carriage-return line-feed") outputs a carriage-return tine-leed and then returns T. 

1 2.4. CHANNEL (the TYPE) 



File names are dependent on the host operating system. The following applies only to TOPS-20 
systems. File names are composed of four parts: the device, the directory, a first file name, and a 
second file name. A typical file name might be: 

"DSK:<MARC>CALCULATOR.MUD" 

MDL will use certain defaults for these four parts, if they are not specified explicitly- These are DSK. 
your working directory, INPUT, and MUD. respectively. These defaults can be overridden by SETGing 
the ATOMs DEV, SNM, NM1. and NM2 to the defaults you desire. These defaults must be STRINGS. For 
some devices, some of the four part3 of the file name are ignored, for example the line printer and the 
terminal (called TPL and TTY). 

Here are some examples of the uses of OPEN: 

<0PEN "PRINT" "TPL:"> opens an output channel to the line printer. 

<0PEN "PRINT- "<MAROF00"> opens an output channel to a disk file called FOO.MUD. 
Remember that the default device is DSK (i.e. the disk) and the default second file name is MUD. 

<0PEN "READ" "F00.TEST"> opens an input channel to a disk file called FOO.TEST in the 
default file directory (i.e. MARC). 

It is good practice to give all of your MDL files a second name of MUD. This allows you to make use 
of ihe MDL default second file name and also makes it easier lor both you and others to find files of 
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MDL I/O 'channels' are represented by an object of TYPE CHANNEL, which is of PRIMTYPE 
VECTOR. The internal structure of a CHANNELS is not frequently examined or manipulated. Those 
interested can consult the MDL manual for details. 



12.4.1. OPEN 

The SUBR OPEN is used to create and return a CHANNEL. It takes two arguments, a mode and a 
file-name, both of which must be STRINGS. If successful, OPEN returns a CHANNEL: otherwise, It 
returns a FALSE containing the reason for the failure and the file-name (both STRINGS.) 

There are two commonly used modes: "READ" and "PRINT". These are used, reasonably enough, 
for input and output, respectively. These modes input and output ASCII characters (i.e. conversion 
I/O). 
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MDL code. In general, files containing only text should be given the second file name TXT. 



12.4.2. FILE-EXISTS? 

FILE-EXISTS? tests for. the existence of a file without creating a CHANNEL, which occupies about 
a hundred machine words of storage. It takes a file-name argument (like OPEN) and returns either T or 
a FALSE containing the reason (a STRING). 



12.4.3. CLOSE 

CLOSE, given a CHANNEL, closes that CHANNEL. An error will occur if any input or output Is directed 
to a CLOSEd CHANNEL. 

It is possible to tell whether a CHANNEL is currently 'open' or has been CLOSEd by looking at the 
first element of the CHANNEL itself. This will always be a FIX. and is the 'channel number' assigned by 
the operating system. A 'channel number' of zero indicates a CLOSEd CHANNEL. 



12.4.4. CHANLIST 

<CHANLIST> 
returns a LIST whose elements are all the currently open CHANNELS. 

12.4.5. INCHAN and OUTCHAN 

The channel used by default for input SUBRs is the local value of the ATOM INCHAN. The channel 
used by default for output SUBRs is the local value of the ATOM OUTCHAN. 

You can direct I/O to a CHANNEL by SETting INCHAN or OUTCHAN (remembering their old values 
somewhere), or by giving the SUBR you wish to use an argument of TYPE CHANNEL. (These actually 
have the same effect, because READ binds INCHAN to an explicit argument, and PRINT binds 
OUTCHAN similarly. 

By the way. a good trick for playing with INCHAN and OUTCHAN within a function is to use the ATOMs 
INCHAN and OUTCHAN as "AUX" variables, re-binding their local values to the CHANNEL you want. 
When you leave, of course, the old LVALs are restored (which is the whole point). 

INCHAN and OUTCHAN also have global values, initially the CHANNELS directed at the terminal 
running MDL. Initially. IHCIIAN's and OUTCHAN's local and global values are the same. Whenever an 
error occurs in MDL. the locul values ol INCHAN and OUTCHAN aro rebound to the global values of the 
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same ATOMs Unless you live dangerously and change the global values of these ATOMs. this will have 
the elfect of redirecting input and output to your terminal, where you are free to go about debugging. 






1 2.5. End-of-File "Routine" 



As mentioned above, an explicit CHANNEL is the first optional argument of all SUBRs used for 
conversion I/O- The second optional argument for conversion- input SUBRs is an "end-of-file routine" 
• that is, something for the input SUHR to EVAL and return, if it reaches the end of the file it is reading. 
A typical end-of-file argument is a QUOTEd FORM which applies a function of yours. The value of this 
argument used by default is a call to ERROR. Note: the CHANNEL has been CLOSEd by the time this 
argument is evaluated. 

End-of-Hle routines are nor used with terminal input! 

The following FUNCTION counts the occurrences of a character in a file, according to its 
arguments. 



<DEFINE CHAR-COUNT (CHAR FILE "EXTRA" CHN) 

#DECL ((CHAR) CHARACTER (FILE) STRING 

(CHN) <0R FALSE CHANNEL>) 
<C0ND (<SET CHN <0PEN "READ" . FILE» 
<REPEAT ((CNT 0)) 

#DECL ((CNT) FIX) 

<C0ND (<--? <READCHR .CHN *<RETURN .CNT» 
.CHAR> 
<SET CNT <+ .CNT 1»)»)» 

The Idea here is that the FORM <RETURN .CNT> will be EVALuated when the end-of-file is reached. 
Had REAOCHR been given only one argument. ERROR' would have been called when end-of-file 
occurred. Also notice that the only way for this REPEAT to terminate is from within the call to 
READCHR. 



1 2.6. Additional I/O SUBRs 

There are a lew other extremely useful I/O routines which should be mentioned here. 
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12.6.1. READSTRING 

READSTRING provides a mechanism of reading characters into a STRING until a specified condition 
is met This condition may be one of two types: 

1 . A specified number of characters has been read. 

2. One of a specified set of characters has been read. 

READSTRING takes a STRING which will be Tilled with CHARACTERS read from its second argument, a 
CHANNEL. An optional third argument specifies the condition on which the READSTRING will 
terminate. If the argument is a FIX. FIX CHARACTERS will be read from CHANNEL. If the argument is a 
STRING. CHARACTERS will be read until one is a MEMBER of the that STRING {MEMO really). In either 
case READSTRING will terminate when the STRING (i.e. the first argument) is filled, should this occur 
prior to the meeting of the 'stop condition', or If the end-of-file is reached. If there is no third 
argument, these latter two conditions are the only ways in which READSTRING will terminate. 

READSTRING returns the number of CHARACTERS read at the time of its termination. Here's how to 
interpret the return from READSTRING (it really isn't all that complicated, but its hard to explain): 

- If there was no third argument, the return will either be the length of the STRING or a 
smaller number. If a smaller number, the end-of-file was reached and that smaller 
number is the number of CHARACTERS read before end-of-file was reached. 

- If the third argument was a FIX and the return was less than that FIX. then end-of-file 
was reached. 

- If the third argument was a STRING, the return was the number of CHARACTERS read 
before the termination CHARACTER was seen. It is very important to realize that the 
termination CHARACTER is not read. In other words, it will not be in the STRING, and the 
next time you try to input from CHANNEL, that termination CHARACTER will be lying in wait. 
Not taking this into account is the cause of many an error for novice MDLers. 

If the terminating event was end-of-file and anofner READSTRING is performed, the end-of-file routine 
will be EVALed. As with the other non-terminal-directed I/O input routines, the default end-of-file 
routine Is a call to ERROR. 

This must seem very confusing, but many of your programs will require reading from the terminal 
and READSTRING is by far the best way to do this in MDL. One of the reasons for this is that 
READSTRING will allow the person inputting to your program to edit his input by means of the rubout 
key and the like. This facility is very hard to simulate if you are reading one CHARACTER at a lime (e.g. 
with REAOCHR). 

A very important warning regarding READSTRING: MDL, you will recall, only starts processing 
terminal input after an escape is typed. This is true also for calls to READSTRING. This means that 
you cannot expect to get a line of input from a user by doing a READSTRING with a 'stop condition' of 
a carriage-return or a line feed unless this is followed by an escape. There are ways around this 
fealure'. but they are beyond the scope of this primer. Please consult the manual or a seasoned 
MDLer for help. 
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Here's a skeleton of a calculator program: 

<DEFINE CALC (.. "AUX" .. CNT (BUFFER <ISTRING 100 l\ >) ..) 
#DECL (... (CNT) FIX (BUFFER) STRING . ..) 
<REPEAT () 

<PRINC " 
>-> 

<SET CNT <READSTRING .BUFFER 

.INCHAN 

<STRING <ASCII 27>>» 
<READCHR .INCHAN> 
<C0ND (<0? .CNT> 

<PRINC " Thanks for using the calculator I "> 
<RETURN>) 
(<--? .CNT 100> 
<PRINC " 
Sorry, that one's too big for me. Please try 
something a bit easier, like 2 + 2.*>) 

(T <CALCULATE .BUFFER -CNT>)»> 

This calculator program is essentially a large REPEAT loop, as you might expect. Each time 
through, it starts by printing a prompt (a carriage-return followed by a closing angle-bracket). It then 
reads some input from the terminal into a STRING which is Initialized at the start of the FUNCTION as 
having a LENGTH of 100. The stop-condition is the presence of an escape (27 decimal in ASCII). 
Since READSTRING will not read the terminating escape, a READCHR is performed. If one were to 
check on what the READCHR was returning, one would find it to always be an escape. If the value of 
the call to READSTRING is zero, no input was typed before the escape. In this example, the program 
terminates. If the return from READSTRING were 100. then the person typing to the program has 
given an excessively long input (this is only true in this example; the FUNCTION could have been 
written to accept much longer inputs) and he is told this. Otherwise, the function CALCULATE is 
called with the user's input (.BUFFER) and the number of CHARACTERS that the user typed (.CNT. I.e. 
the number of valid" CHARACTERS in .BUFFER). With any luck. CALCULATE will do something useful 
with its arguments, like performing the requested calculation and printing the result(s). 

Could you write this skeleton without using a REPEAT? There are at least two other reasonable 
ways. II you cannot, try rereading Chapter 10. 



12.6.2. PRINTSTRING 

The SUBR PRINTSTRING Is analogous to the SUBR READSTRING. It takes three arguments, a 
STRING (the STRING to print), a CHANNEL (on which to print it), and a FIX (the number of characters 
from the STRING to print). If the LENGTH of the STRING is less than the third argument. 
PRINTSTRING just print3 the STRING. In any event, PRINTSTRING returns the number of characters 
actually printed. 
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The entire state of MDL can be saved away in a file lor later restoration: this is done with the SUBRs 
SAVE and RESTORE. This is a very different form of I/O from any mentioned up to now; the file used 
contains an actual image of your MDL address space and is not, in general, "legible" to other MDL 
routines. RESTOREing a SAVE file is much faster than re-READing ihe objects it contains. 



12.7.1. SAVE 

Calling the SUBR SAVE with a file-name will save away the entire state of your MDL in a file with that 
name. It then returns "SAVED". When a RESTORE is done later (to return to the 'saved' state), the call 
to SAVE returns "RESTORED". 

<DEFINE SAVE-IT ("OPTIONAL" 

(FILE "<GUEST>PUBLIC.SAVE") 
"AUX" (SNM •"•)) 
<SETUP> 

<C0ND (<-? "SAVED" <SAVE -FILE» 
<CLEANUP> 
"Saved.") 
(T 
<PRINC " 
Amazing program at your service. "> 
<START-RUNNING>)» 



12.7.2. RESTORE 

RESTORE, given a file-name, completely replaces the contents of the MDL from that file, including 
the state of execution existing when the SAVE was done and the state of all open I/O CHANNELS. If a 
file which was open when the SAVE was done does not exist when the RESTORE is done, a message to 
that effect will appear on the terminal. 

A RESTORE never returns (unless it gets an error): it causes a SAVE done some time ago to return 
again (this time with the value "RESTORED"), even if the SAVE was dono in the midst of running a 
program. In the latter case, the program will continue its execution upon RESTOREation. 



12.8. PARSE, LP ARSE, and UNPARSE 

These SUDRs are borderline I/O routines PARSE, given a STRING, uses READi algorithm for 
converting text into MDL obiccls and returns the lirst one found. 



SUCTION 127 CNF IJT/OUTPUT 



1 °° THE MOL PRIMER 



n 



12.9.2. SNAME 

sS—HSF™ = =» =- sssaaaa 

<SNAME> is identical in effect with <GVAL SNH>. that to. it returns the current d/r used by default. 






<SET STR "(FOO a 2.3) HO-HUM">J 
"(FOO 1 2.3) HO-HUM- 
<PARSE .STR>$ 
(FOO 1 2.3) 

in ^^l^TT^IES retUmS 3 , LIST COntainin 9 a " of *• items which READ would have Found 
in tne STRING. Using the same example: 

<LPARSE ,STR>S 
((FOO 1 2.3) HO-HUM) 

MDL pSlNTin a me *"""* °' ^^ ^^ * M ° U **"*' UNPARSE retUrns a STRIN *' suitable for 

<UNPARSE (A B C)>$ 
"(A B C)- 
<UNPARSE 3.4> 
"3.40000000" 

All of these SUBRs are very expensive CPU-wise. They should be avoided if at all possible. 



12.9. Other I/O Functions 

12.9.1. FLOAD 

JS^JS^J!!S3R READS and EVALua,ea everything in the file! in order, and returns 
DONE , If .he filespec.f,ed does not exist. FLOAD returns a FALSE containing the reason why. 
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12.9.3. FILE-LENGTH 

FILE-LENGTH, given a CHANNEL open for input, returns the length in characters of the file 
associated with that CHANNEL. Doing a FILE-LENGTH on an terminal CHANNEL is silly. 



12.9.4. RESET 

<RESET channel> 

returns channel, after "resetting" it. Resetting a CHANNEL is like OPENing it afresh, with only the 
file-name slots preserved. For an input CHANNEL, this means emptying all input buffers and, if it is a 
CHANNEL to a file, doing an ACCESS to on it. For an output CHANNEL, this means returning to the 
beginning of the file - which implies, if the mode is not " PRINTO" . destroying any output done to It so 
far. If the opening fails (for example, if the mode slot of channel says input, and if the file specified in 
its real-name slots does not exist), RESET (like OPEN) returns # FALSE (reason.-srr/ng lile-spoc-.string 
status://'*)* 



12.9.5. RENAME 

RENAME is for renaming and deleting files. It takes two kinds of arguments: 

- (a) two file names, separated by the ATOM TO 

- (b) one file name 

Omitted file-name parts use the same values by default as does OPEN. If the operation is successful. 
RENAME returns T. otherwise #FALSE (reason;string status:tlx). 

In case (a) the file specified by the first argument is renamed to the second argument. For example: 

<RENAME "F00" TO "8AR , *> ; B Rename F00.MUD to BAR. MUD." 

In case (b) the single file name specifies a file to be deleted. For example: 

<RENAME "<MAROF00.MU0"> ;"0elete file FOO.MUD 

from MARC's directory." 
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12.10. Terminal CHANNELS 

MDL automatically adds a line-feed, whenever a carriage- return is Input from a terminal CHANNEL. 
In order to type in a lone carriage-return, a carriage-return followed by a rubout must be input. 
PRINT. PR INI and PRINC do qoJ automatically add a line-feed when a carriage-return is output. This 
enables overstriking on a terminal that lacks backspacing capability. It also means that what goes on 
a terminal and what goes in a file are more likely to look the same. 



12.10.1.TYI 

TYI. given a terminal input channel, returns one CHARACTER from It when it is typed, rather than 
after S (ESC) is typed, as is the case with READCHR Novice MDLers tend to use TYI to read input 
from the terminal. This is not recommended as a rule. Use READSTRING instead. 



INPl I T/OUTPUT SECTION 12.10 



THE MDL PRIMER 109 



13. Making Tables 



It seems that MDL programmers are always making tables of one thing or another. Someone's 
Whois program may want a table relating a person's login name lo his full name. Someone's 
Calculator program may want a table to associate arbitrary variable names with values. 

There are any number of ways to implement tables for these types of purposes; some of these may 
already have come to mind. For our discussion, let's use the example of a calculator program which 
accepts inputs of the form: 

A - 4 + 3 

8 - (A • A) + 7 

Without considering the actual details of how the calculator might be written, something must be 
done to keep track of the fact that the variable A has a value of 7. and that B has a value of 56. What 
follows are a number of different approaches to solving this sort of problem. Each should be 
examined carefully and the advantages and disadvantages noted. 



13.1. Use a LIST 

This is the most common and possibly the most useful approach. For the given example, we can 
create a LIST, which, for example, is the GVAL of the ATOM VARIABLES. 

.VARIABLES* 
(A 7 B 68) 

If one wants to add a new variable, say C, with a value, say 100. one can do the following: 

<SETG VARIABLES (C 100 I . VARIA8LES)> 
To check if a variable, say D, has a value, one can do this: 

<MEHQ D ,VARIABLES> 
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To actually get D's most recent value, 

<C0ND (<SET M <MEMQ D ,VARIABLES» 
<2 .M>)> 

This COND clause returns a FALSE if D doesn't have a value; otherwise, it returns the value. 

Removing variables Irom the LIST can be done with PUTREST. As an exercise, write a FUNCTION 
which, given a variable name and a LIST (like the one we used above), removes the variable and its 
value from the LIST. Be sure you handle the case in which the variable isn't in the LIST. One 
solution to this is given at the end of the chapter. Don't peek, and don't be too frustrated. The 
FUNCTION isn't that easy to write. 

LISTs are very space-efficient. However, while LISTs are practical for smallish tables, larger ones 
will tend to become very slow to access, since LISTs are not random-access structures (see Chapter 
7). If your table needs to be more than a hundred elements long, you should probably try somothing 
else. 



13.2. Use a VECTOR 

Think twice before you do. As we saw in Chapter 7. VECTORS have the property that they cannot be 
added to and cannot have elements removed without creating an entirely new structure (which is very 
garbage-creating). Therefore, using VECTORS is not a good idea unless the table is 'preformed' and 
elements need never be removed or added. If you have a table of ordered elements of relatively fixed 
size, use of VECTORS with some sort of binary-searching algorithm is appropriate. For the calculator 
example, don't use a VECTOR. 



13.3. Use an ATOM 

Another simple approach would be to SETG the variable name (which is an ATOM) to it3 value. 
Then, you can use GASSIGNED7 to check if it has a value. GVAL to get it, and GUNASSIGN to remove it. 
Lookup using GVALs is moderately fast, but there Is a problem. Imagine the result of your poor 
calculator user setting a variable whose name is the name of your program. The use of SET and LVAL 
is also perilous. 
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13.4. Use an Association 

MDL allows you lo assign a value to a pair of MDL objects. This can be done using the SUBR 
PUTPROP. The value of such an 'association' can be retrieved with the SUBR GETPROP. 

<PUTPROP MICHAEL AGE 28>$ 

MICHAEL 

<GETPROP MICHAEL AGE>$ 

28 

One can associate any three MDL objects using PUTPROP. A useless, but legal, use might be: 

<PUTPROP £1 2 3] (4 6 6) "FOOBAR">J 

[1 2 3] 

<GETPROP £1 2 3] (4 6 0)>$ 

#FALSE () 

Why did the last GETPROP return #FALSE ( )? Hint: Are either of the arguments to GETPROP --? to 
the arguments to PUTPROP? 

By giving PUTPROP only two arguments, it returns what GETPROP would have returned, and then 
removes the association. 

<PUTPROP MICHAEL AGE>$ 

28 

<GETPROP MICHAEL AGE>$ 

#FALSE () 

In the calculator example, one could do something like this: 

<PUTPROP A VARIABLE 7>$ 

A 

<PUTPROP B VARIABLE 66>S 

B 

to set the variables' value. One would retrieve the values like this: 

<GETPROP A VARIABLE>$ 

7 

<GETPROP B VARIABLE>$ 

66 

Associations are fast 'they use a hashing scheme with a fixed number of buckets), but rather 
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space-inefficient Large numbers of them will lend to crowd your core-imago. 

13.4.1. Hashing 

Hashing, for those unfamiliar with the notion, Is an algorithm for table lookup which is based on a 
directed search . A hash lable can be thought of as a VECTOR of LISTs These LISTs are commonly 
called buckets Each actual item in the hash table is found in one of these buckets'- What makes 

.h 3 , 5 , J°. ' S ,hefe iS 3 Simp,e a, 9° ri,nm ,or determining which 'bucket' an item is in. Once 

that determ.nat.on ls made, the 'bucket' is searched linearly for the item. Thus, a hash lable of length 
100. which contains 1000 items, would have an average of 10 items per 'bucket'. Thus, the access 
time for looking up an .tern would be the same as that for MEMQing a LIST of 10 elements plus the 
small overhead of determining which 'bucket" the item is in. This is obviously much faster than 
linearly searching a LIST of 1000 elements, by a factor approaching 100 



13.5. Use an OBLIST 

° B " S T* f e ,ab,es o( A ™ Ms wnicn are hash *d '" such a way that finding an ATOM in one is very 
fast. Similarly, inserting and removing ATOMs is simple. 

tmiSSmSiS ° DL - IST . I. y0 u U L OWn, USS the SUBR M0BLIST < Ha *° OBLIST). which takes a name 
buckets should be'prime? bucke, s 'or the OBLIST (defaultly 17). For best results, the number of 

<SETG FOOBAR <M0BLIST FOOBAR 7»$ 
#0BLIST |[() () () () () () ()] 

Note that there are seven empty LISTs in the OBLIST - you guessed it ... each LIST is a bucketl 

uJui'lTSiS" ESEFSSS?**' us f™ e SUBR IHSERT To remove *" AT0M from •" 0BLI ST. 

^f 1™ BR REM0VE - To look up an ATOM in an OBLIST. use the SUBR LOOKUP. Each of these 
three SUBRs takes a STRING, the PNAME of the ATOM, and an OBLIST. 

<INSERT "MIKE" . F00BAR>$ 
MIKEI -FOOBAR 
, FOOBARS 

#0BLIST IC() () () () (MIKEI-FOOBAR) () Ml 

(LOOKUP "MIKE" .F00BAR>$ 

MIKEI-FOOBAR 

<L00KUP "BLETCH" . F00BAR>$ 

#FALSE () 
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There's something new here, namely the suffix to the name of the ATOM; an exclamation point, a 
hyphen, and an ATOM. This suffix Is called an 'oblist-trailer" or simply a 'trailer'. It is there so that 
READ and PRINT can distinguish this new ATOM whose PNAME is FOOBAR from an ATOM on another 
OBLIST whose PNAME is F008AR. Therefore, to directly reference the ATOM ol PNAME BLETCH in the 
FOOBAR OBLIST. one must type in the following: 

BLETCHI-FOOBAR 

In fact, typing BLETCH I -FOOBAR causes READ to create an ATOM with PNAME BLETCH in the FOOBAR 
OBLIST if none already existed. Not only that, but typing FROB I -MUMBLE causes READ to create an 
ATOM ol PNAME FROB in the MUMBLE OBLIST {creating a MUMBLE OBLIST /' necessary) if none 
already existed. 

If you are interested in a more complete description of OBLISTs, refer to the next section. To 
continue with the calculator example, we might start by creating an OBLIST for variables. 

<SETG VARIABLES <MOBLIST VARIABLES»$ 
ffOBLIST .... 



Then, we assign values to A and B as follows; 



<DEFINE SET-VARIABLE (NAM VAL "AUX" (PNM <PNAME . NAM> ) ) 

#OECL ((NAH) ATOM (VAL) ANY (PNM) STRING) 

<SETG <COND (<LOOKUP -PNM .VARIABLES>) 

(T <INSERT .PNM . VARIABLES> )> 
.VAL>>* 
SET-VARIABLE 
<SET-VARIABLE A 7>$ 
7 

<SET-VARIABLE B 68>$ 
66 

To retrieve values, we might do this: 

<DEFINE GET-VARIABLE (NAM "AUX" ATM) 

#DECL ((NAM) ATOM (ATM) <0R FALSE ATOM>) 
<CONO (<SET ATM <LOOKUP <PNAME .NAM> .VARIABLES>> 
,.ATM)»S 

GET-VARIABLE 

<GET-VARIABLE B>$ 

66 

<GET-VARIABLE D>$ 

#FALSE () 

Using ODLISTs in this way solves tho problem mnntioned earlier ro(j.irfling the use 0' ATOMs; thai Of 
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Zl^l« ,hL ,' y . 9 AT ° MS '" yOUf ° Wn Pfiuale 0BLIST ' ,nere is no *™9* °< mistakenly 

Chang ng the value of someone else's (or your own...) ATOM Now. your calculator user can use 
vanable names wh.ch are the same as those of your calculator FUNCTION* without tear of disaster. 

To summarize, using OBLISTs is fast. ATOHs are rather large; about the same size as an 

oTtTsT cTn H^Z*** *Z T^? T* '° r "• octe «o"» is * «*«* ^ze. ,he hashing .able "r " 
Sni ™ k, be J etermined whe " *}* OBLIST is created. ATOHs are more versatile than associations, 
a^socfations """ "^ °° d M ° L pro 9 rammera ' 9 ivo " ' h * choice, will use OBLISTs ove 



13.6. OBLISTs, READ, and PRINT 

tof'SGETInV"?^ 4 , V^ 1 T" 9 GE ° RGE t0 MDL CBU * 6d READ l ° "' ooK up lhe ^presentation 
lot GEORGE] m a table it keeps for such purposes...." It should now be clear that the "table it 

keeps is. m fact, an OBLIST. and that it "looks up the representation" by using the luBR LOOKUP 

You are now ready to understand what, in fact, REAO does. 



When READ encounters something that it determines must be an ATOM (i e it can't be anvthino 

ATO e M ^TZlfTJ PNAME A ^- nt ' a " y '*" a " ° f ,hS ° 8LISTS * -OBL^T i." mlfvAL of he 
SS??ST?^fTLT«TT T ff n^r'^ B l LIS \ , ° ^ 3 LIST °' 0BLI STs. Initial.y. .OBLIST has two 
OBl.rSTs.nu. the INITIAL OBLIST (user ATOMS) and the ROOT OBLIST (MDL s ATOMs) The ATOMs 
wh.ch poml to the F/SUBRs a), live in ROOT.] The value of the first LOOKUP to succeed becomC^ht 
!0B?ISt5T ,0 READ - " ^ PMAME *" f ° Und " ^ AT ° M Wi ' h that PNAME Ts IN^ER^Tnto « 

If READ (of ATOMs) were written in MDL. it might look like this: 



<D£FINE READ-ATOM (STR) 
#DECL ((STR) STRING) 
<COND (<MAPF <> 

<FUNCTION (OBL "AUX" ATM) 

#DECL ((OBL) OBLIST (ATM) <0R FALSE ATOM>) 
<COND (<SET ATM <LOOKUP .STR .OBL» 
<MAPLEAVE .ATM>)» 
.OBLIST>) 
(T <INSERT .STR <1 .OBLIST»)» 



i 



However, if an explicit trailer 



is given, the ATOM is placed in the OBLIST named in the trailer 
MI T%T ™hL SSSvJS example. A I -B I -C I -D I -E Is an ATOM with PNAME A which is in an 
p' L Jf " h °f mama's an ATOM with PNAME B which is on an OBLIST whoso name... The ATOM wHh 

EfcSLf V£ T; -, m ° ne th ° ° BLTSTS m -° DLIST - When PRINT a,tem P ,s !o »»""* «" ATOM of 
th.s kind, H pnnts traders until one of the OBLIST names can be found on an OBLIST in .OBLIST 
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14. Debugging MDL Programs - An Introduction 

If you have ever written a program which worKs completely correctly on the first attempt, you most 
likely have benefited from divine intervention. In the more likely event that one ol your MDL programs 
is "buggy", you will see messages which look like this: 

•ERROR* 

reason 

Information-about-error 

function-which-generated-lt 

LISTENING-AT-LEVEL n PROCESS m 

The Information-about-error may be one or more than one object. The n Is an indication of how many 
levels of errors have occurred, and m should be completely ignored- If you ever see a number other 
than 1 in that position, you probably don't need to be reading this. 

The meaning of this gobbledygook Is that the MDL SUBR ERROR was invoked. This may have 
happened from an explicit call to ERROR, as in the following: 

<ERROR YOU-LOSE BECAUSE MY-FUNCTION> 

More likely, however, the MDL interpreter discovered an error in your program, such as a variable 
without a value, or a bad argument to a function, and called ERROR internally. The effect is the same: 
•ERROR* is printed, followed by all of the arguments to ERROR, and MDL starts LISTENing at the next 
higher level. In other words. LISTEN has been called recursively. 

In Ihe remainder of this chapter, we will be discussing the debugging of a particularly trivial error in 
a sample FUNCTION. Please refer frequently to the figure at the end of the chapter in which parts of 
the example are diagrammed and commented. 

In order to correct an error, it is necessary to have some information about the history of MDL's 
execution at the time of the error. To do this, the function FR& is called, usually without arguments. 
Let us assume that the following FUNCTION is being called as follows: 
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<DEFINE GT10 (ARG) <G? .AGR 10»$ 
GT10 

<GT10 11>$ 
•ERROR- 
UNBOUND-VARIABLE 
AGR 
LVAL 
LISTENING-AT-LEVEL 2 PROCESS 1 



<FR&>$ 




ERROR 

1 LVAL 

2 EVAL 


[UNBOUND-VARIABLE 1 -ERRORS AGR LVAL] 

[AGR] 

[.AGR] 


3 EVAL 

4 EVAL 

6 LISTEN 


[<G? .AGR 10>] 
[<GT10 11>] 

E3 


TOPLEVEL 





What is shown here, one to a line, are the FRAMES which have been generated by MDL. starting from 
the one called LISTEN, which is where MDL was waiting when the FORM <GT10 11> was input. The 
lines above this one are the steps which MDL took until the error occurred, namely in the code lor 
LVAL. Each line has a number, by which the FRAME can be identified, the FUNCT of the FRAME 
(always an ATOM), and the ARCS of the FRAME (always a TUPLE). For these purposes, a TUPLE can be 
considered to be a VECTOR. Given a FRAME number, the FRAME can bo referenced by invoking the 
function FRM. as follows: 

<SET F <FRM 3»$ 
#FRAME EVAL 
<FUNCT .F>$ 
EVAL 

<ARGS . F>J 
[<G? .AGR 10>] 

Having gotten this far. it has become obvious that the problem is that the function GT10 is incorrect, 
in that the reference to AGR was intended to be a reference to ARG. What follows are some ways of 
fixing the problem, all of which will work. Although this is a trivial example of an error, as the problem 
itself was easy to spot, the methods of error recovery are always the samel 



14.1. Method 1: Start Over 

Edit the FUNCTION with your favorite text editor and reload it. relype it in to MDL directly, or 
whatever. Then invoke the SUUR ERRET with no arguments. This will cause MDL to relurn !o ils "top 
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level", i.e. LISTENING-AT-LEVEL 1. All parts of the execution In progress including all ATOMIC 
bindings (except those made at "lop level") will be lost. 

<ERRET>S 

LISTENING-AT-LEVEL 1 PROCESS 1 



14.2. Method 2: Forcing FRAMES to Return Values 

It is possible to cause MDL to force an arbitrary FRAME to return an arbitrary value and to continue 
execution trom that point. This is done by calling ERRET with either one or two arguments. The first 
argument is the value for the FRAME to return, and the second, if given, is the FRAME which is to return 
that value. If no second argument is given, the FRAME immediately previous to the ERROR FRAME will 
be used as a default. 

<ERRET 9>$ 
0FALSE () 

What happened was that the LVAL FRAME (i.e. <FRM 1> was caused to return 9. Execution 
continued, such that the EVAL FRAME above (i.e. <FRM 3» also returned 9, and the next frame 
evaluated <G? 9 10>. which returned an empty FALSE, which became the value of the call to GT10. 
Notice that in this case, the fact that 11 was originally passed to GT10 has become unimportant. 
Another way of doing the same thing would have been to say 

<ERRET 9 <FRM 1»$ 

#FALSE () or 

<ERRET 9 <FRM 2»S 

#FALSE () 

However, saying 

<ERRET 9 <FRM 3»J 

has a different result. What happened was that the FORM <G? -AGR 10> was forced to return 9. 
Since that FORM was the last in the body of the FUNCTION, the result of its evaluatiDn became the 
result of the evaluation ol the FUNCTION. Therefore, GT10 returned 9. 



SECTION 14 1 OrnUCiGING MDL PROGRAMS fit* INTRODUCTION 



118 THE MDL PRIMER 

14.3. Method 3: Use EDIT to Repair your FUNCTIONS 

In the lasl method, nothing has been done to correct the real problem, i.e. that the program has a 
bug in it. One way to solve this is to use the MDL editor, a function called EDIT to alter the program 
itself. EDIT is usually invoked with the name of a FUNCTION to be edited as the only argument. You 
will now be "talking" to the MDL editor. Commands to the editor should be terminated with an 
escape, and are one or two characters followed by some arguments, which are usually optional. 
EDIT will display after each command your current "location" in the FUNCTION you are editing. To 
move around, the commands L (left), R (right), U (up), and D (down) are used. These may be followed 
by a numerical argument, the number of times to perform the command. The arguments must be 
preceded by a space. A vertical bar Is used here to indicate your "position" in the edited FUNCTION. 
In the real MDL editor, the "position" may be indicated by some other characters. 

<EDIT GT10>$ 

♦FUNCTION (| (ARG) <G? .AGR 10>) 

R 2S 

♦FUNCTION ((ARG) <G7 .AGR 10> |) 

LS 

♦FUNCTION ((ARG) | <G? .AGR 10>) 

OS 

<| G? -AGR 10> 

D$ 

ERROR. YOU CAN'T GO DOWN 

<| G? .AGR 10> 

RS 

<G? J .AGR 10>) 

To alter the FUNCTION the following commands may be used: I (insert), K (kill), and C (change). Insert 
takes any number of objects as arguments and inserts them all to the right of your "location". Kill 
takes an optional number (default 1) and removes that many objects from the 'right of your "location". 
Change takes one argument and changes the object to the right of your "location" to it. 

<G? | .AGR 10> 

C .ARGS 

<G? | .ARG 10> 

This has had the effect of fixing the error in the program. To exit the editor, use the O command. 

<G? | .ARG 10> 
QST 

The T was the returned value of the call to EDIT. Now, a look at the FRAMEs using FR& shows the 

following: 
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<FR&>$ 



ERROR 


[UNBOUND-VARIABLE! -ERRORS A6R LVAL] 


1 LVAL 


[AGR] 


2 EVAL 


C-AGR] 


3 EVAL 


[<G? .ARG 10>] 


4 EVAL 


[<GT10 11>] 


6 LISTEN 


C3 


TOPLEVEL 





Make sure you understand what has happened. The way the editor works for the case of the C 
command is to PUT the argument to C into the structure. The FORMs contained in the ARGSs of 
FRAMES are simply pointers directly into the FUNCTION being executed. Thus, the PUT into the FORM 
will change the argument to the FRAME which points to it! This is extremely important, and is 
illustrated in the diagram at the end of the chapter. Think about this very carefully if you don't 
understand this, and then be sure you convince yourself of why the argument to <FRM Z> has not 
changed. 

Now that you have done this, it would be useful if you could tell MDL to go back and retry <FRM 3>. 
In fact you can. using the SUBR RETRY which takes a FRAME as an argument, and simply pretends 
that nothing past that point in execution has ever happened- This works completely as long as the 
execution below that point hasn't had any side-effects. A MDL function is said lo have side-effects If it 
does anything other than manipulate its local variables and return a value. Stated another way. a 
function with no side-effects is a black-box with an input (arguments) and an output (value), but no 
effect on the 'outside world'. The most blatant side-effecting SUDRs are PUT, PUTREST. SETG, and 
PRINT. SETtiny ATOMs which are not bound in a currently executing FUNCTION also has side-effects. 
In a purist structured -programming sense, no function should have side-effects (with the obvious 
exception of printing output). However, there are certainly cases in which PUT. PUTREST, and SETG 
are tremendously useful, if not vital. Care should be taken, however, since many bugs can be traced 
to one function's causing a side-effect which causes another function to Fall. 





<RETRY 

T 


<FRM 


3»$ 


Quest 


on: Would 








<RETRY 


<FRM 


4»$ 



have the same effect? The answer Is yes. because you are restarting from an earlier level of 
execution. What would be the effect of RETRYing <FRM 6>? Hint It isn't a return of T. What would 
be the effect of RETRYing <FRM 2>? Hint: It isn't good. If you aren't completely sure of the answer to 
these, try it in MDL. 
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14.4. Method 4: Altering FRAMES / RETRY 

Let's try the following, starting Irom the point of the error; 

<SET X <1 <ARGS <FRM 3»»$ 

<G? .AGR 1Q> 

<PUT .X 2 *.ARG>S ;"Why the quote?" 

<G? .ARG 10> 

<RETRY <FRM 3»$ 

T 

We have done the same thing as we did using method 3. but from a different angle. Question: What 
does the FUNCTION GT10 look like now? Hint: Not the same. If you don't see this, you didn't 
understand why editing the FUNCT I ON worked either. 



1 4.5. Summary 

We have presented four different ways of handling errors in MDL. This list is not exhaustive, but it 
should provide enough background to enable you to handle most situations. If this chapter has been 
totally confusing, ask someone for help and use method t in the meantime. .Notice that method 2 
does not prevent the same error from recurring: it merely corrects the current instance of that error. 
Methods 3 and 4 correct the general problem and the current instance of the error generated by the 
problem. However, even though the FUNCTION is changed in your MDL, you still must alter it using 
your favorite editor at a later time (or write out an updated copy of the file directly from MDL). The 
changes made while in MDL are not reflected in your files! They will, however, allow you to proceed 
without moving back and forth constantly between MDL and your editor. 

MDL has many other debugging aids including breakpoints (in EDIT), tracing, monitoring the 
values of local and global variables, and more. For a detailed description of these facilities, consult 
The MDL Programming Environment [Lebling 80]. 
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FORM | 



ATOM 



AGR 



ERROR 
FRAME 



Selected FRAMES during execution of GT10 as described in the text. Note that 
the FRAHEs p oint directly at the structure of GT10 (e.g. the FORM in FRM3 is 
--? to the second element of the FUNCTION). 



* FUNCTIONH ARG) <G? AGR lO>) 
„'l '-?-' J ' I 

y / s 



FUMZTION 



c 



/ 
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s 



LIST 



E 



=T 



• 



FORM 



ATM 



FRM 

3 



x FRM 
1 



FRM 
O 



ARG 



ATOM 



G ? 
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y 


FRM 


FORM 
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FORM 


























i 


10 




— 1 














V' 


J.,*- atom| — 




ATOM O 




**V, 




LVAL 


ARC 


















ATOM 






ATOM 


o 






LVAL 


AGR 



The dotted arrow and cross indicate the state of pointers alter 
the FUNCTION has been edited. Notice that <FRM Z> still 
points to .AGR . even though <FRM 3> points to <G? -ARG 
3>. 



Figure 14-1: Diagram for the example in this chapter 
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